Connect Velocity with OAuth
Let customers authorize your service to act through the Velocity API as themselves.
Register your application
As a workspace admin or owner, open Settings → OAuth Apps → Create OAuth App. Choose External service, register your callback URLs and select the maximum scopes you need. Your workspace owns the app; each customer independently chooses the workspaces it may access. API applications are available on every plan; individual product features retain their own limits.
Hosted services are confidential clients: keep the one-time client secret on your server. Public/native clients use PKCE without a secret. Register HTTPS callbacks; HTTP is allowed only on localhost, 127.0.0.1 or [::1] for local development/native clients. Callbacks cannot contain fragments, credentials or wildcards. HTTPS callbacks match exactly; loopback callbacks allow a variable port with the registered path and query.
The app access model and client type are fixed at creation. Disabling an app ends its grants immediately. Changing scopes or callback URLs also revokes previous approvals; enabling it again requires customers to reconnect. To replace a lost or compromised secret, register a replacement confidential client, migrate connections and delete the old application.
Authorize with explicit consent
Generate an unpredictable state and a unique 43–128 character PKCE verifier for each sign-in. Bind them to the initiating browser session. Redirect the browser to:
https://velocity.quest/api/oauth/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=https%3A%2F%2Fyour-service.example%2Fcallback
&scope=read%3Aissues%20write%3Aissues%20read%3Ateams
&state=RANDOM_BROWSER_BOUND_STATE
&code_challenge=BASE64URL_SHA256_VERIFIER
&code_challenge_method=S256Velocity asks the user to approve the registered application, requested capabilities and one or more workspaces. No workspace is selected automatically for external services. Denying creates no grant. Additional scopes or workspaces require another explicit consent; newly joined workspaces never gain access automatically.
At your callback, verify the exact state, the issuer parameter iss=https://velocity.quest, and any error before exchanging the code. Codes expire after 60 seconds and can be exchanged once. Do not log callback URLs, codes, tokens or secrets.
POST https://velocity.quest/api/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&client_id=YOUR_CLIENT_ID&code=CODE&redirect_uri=REGISTERED_CALLBACK&code_verifier=VERIFIERConfidential clients must additionally authenticate using HTTP Basic (form-encode each credential before base64 encoding) or client_secret in the form body. Public clients send only their client ID and PKCE verifier. The response contains access_token, refresh_token, expires_in=3600 and the granted scope. Store credentials encrypted on your server.
API permissions
Send Authorization: Bearer ACCESS_TOKEN. Use X-Workspace-Slug to select an approved workspace. Writes require a current member/admin/owner role in that workspace; guest grants cannot write. Existing product role and feature checks still apply. A write scope includes reads for its resource.
| Scope | Supported GraphQL operations |
|---|---|
read:issues | issues, issue; labels and statuses; issue comments, activities, relations and subscribers, including their collection pages |
write:issues | Create/update/delete and batch update/delete issues; create/remove issue relations; subscribe/unsubscribe yourself |
read:projects | project, projects, projectsPage, projectMilestonesPage |
write:projects | Create/update/delete projects and milestones |
read:teams | team, teams, teamsPage, teamMembersPage |
read:workspaces | workspace, workspaces, workspacesPage, workspaceMembersPage (also requires read:users) |
read:users | me and user; public profile identity, plus approved-workspace member identities when the corresponding workspace/team scope is present |
Scopes are checked on nested fields as well as roots. Selections are limited to 20 nesting levels and a bounded traversal; use smaller paginated operations. For example, querying an issue’s project needs read:projects, and its team needs read:teams. Human identity projections include ID, display name, avatar and timestamps. Email addresses, preferences and timezone are excluded. Workspace settings/invitations, billing, account security, credential management, AI execution, imports/exports and other unlisted operations are unavailable to external app grants. These permissions do not grant MCP or automation API access.
REST endpoints
| Endpoint | Permission / response |
|---|---|
| GET /api/v1/identity | Any external API grant: own user ID, application ID, granted scopes and currently authorized workspace IDs/names/slugs |
| GET /api/v1/issues?limit=50&after=CURSOR | read:issues: edges with issue nodes, pageInfo and totalCount; limit 1–100 |
| GET /api/v1/issues/ID | read:issues: issue details; identifiers resolve within the selected workspace |
| POST /api/v1/issues | write:issues: JSON CreateIssueInput, including teamId and title; returns the created issue with HTTP 201 |
| PATCH /api/v1/issues/ID | write:issues: JSON UpdateIssueInput; returns the updated issue |
| DELETE /api/v1/issues/ID | write:issues: deletes the issue |
curl https://velocity.quest/api/v1/identity -H "Authorization: Bearer $ACCESS_TOKEN"
curl https://velocity.quest/api/v1/issues \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Workspace-Slug: customer-workspace" \
-H "Content-Type: application/json" \
-d '{"teamId":"TEAM_UUID","title":"Created by an external service"}'The REST issue facade executes the same GraphQL operations and authorization checks. It does not grant access to unrelated management REST routes. GraphQL remains available at /api/graphql for the supported operations above.
Read an issue through GraphQL
With read:issues, fetch an issue in an approved workspace. Select only fields supported by your granted scopes; adding a nested project or team requires its corresponding read permission.
curl https://velocity.quest/api/graphql \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Workspace-Slug: customer-workspace" \
-H "Content-Type: application/json" \
-d '{"query":"query($id: ID!) { issue(id: $id) { id identifier title descriptionText } }","variables":{"id":"ISSUE_UUID"}}'
curl https://velocity.quest/api/v1/issues/ISSUE_UUID \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Workspace-Slug: customer-workspace"Refresh, disconnect and errors
Access tokens last one hour. For every OAuth client, refresh tokens expire after 90 days without successful rotation. POST to the token endpoint with grant_type=refresh_token, refresh_token and client_id, plus client authentication for confidential clients. Atomically save both replacement tokens; serialize refreshes per connection. Never retry an old public-client refresh token after rotation: replay revokes the entire grant. Confidential clients have a single-use 30-second concurrency grace window, then the same replay protection applies. Refresh preserves the original scopes and workspace set.
Existing MCP and CLI tokens issued without an expiry receive a full 90-day transition window when this policy is introduced. New sign-ins and successful refreshes start a fresh 90-day window. An expired grant is revoked, including its access tokens; start browser sign-in again instead of retrying the expired refresh token.
# Confidential service: run on your server, never in browser code.
curl https://velocity.quest/api/oauth/token \
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "client_id=$CLIENT_ID" \
--data-urlencode "client_secret=$CLIENT_SECRET" \
--data-urlencode "refresh_token=$REFRESH_TOKEN"Public clients omit client_secret. Before another API call, replace both saved tokens with the returned pair. Keep credentials out of logs, shell history and shared terminals; these placeholders belong to your service's secure credential storage.
When refresh returns invalid_grant, restart consent. A 401 invalid_token from REST means refresh or reconnect; 403 means insufficient scope, role or selected workspace and cannot be repaired by repeatedly refreshing. GraphQL reports corresponding errors in its errors array. REST returns 400 for invalid inputs, 404 for unavailable resources, 429 with Retry-After for rate limits, and 503 for temporary identity lookup failures. External REST has a shared 300 requests/minute user budget; issue calls also use the existing GraphQL budget. Do not automatically retry mutations after a lost response.
Disconnect by POSTing token, client_id and client authentication to /api/oauth/revoke. Unknown tokens return 200; recognized tokens revoke the entire consent family. Users can also revoke individual connections in Settings → OAuth Apps → Your connected applications. Leaving/removal from an authorized workspace revokes the grant; reconnect for the remaining workspaces. Disabling/deleting the app prevents further access. Existing OAuth clients retain their own policies.
curl https://velocity.quest/api/oauth/revoke \
--data-urlencode "client_id=$CLIENT_ID" \
--data-urlencode "client_secret=$CLIENT_SECRET" \
--data-urlencode "token=$REFRESH_TOKEN"After disconnecting, remove the locally stored credentials. Public clients omit client_secret here as well. A successful revoke returns HTTP 200 with an empty JSON object.
Runnable hosted-service example
The Download the Node.js example demonstrates browser-bound state, PKCE, issuer validation, identity discovery, issue creation, serialized refresh and disconnect. Run it with an independently registered application and test account; it requires no SDK dependencies. It is a local demonstration, and itssetup README describes the production storage and authentication requirements.
curl --fail --location --output server.mjs \
https://docs.velocity.quest/examples/oauth-service/server.mjs
node server.mjsUse Node.js 20 or newer. Before starting, register http://127.0.0.1:8787/callback and the scopes read:issues write:issues read:teams read:workspaces. Set VELOCITY_CLIENT_ID and, for a confidential client, VELOCITY_CLIENT_SECRET in your private environment. Public clients omit the secret. Open the printed local URL to connect a test customer, select workspaces and try the issue, refresh and disconnect forms. The downloaded script has no dependencies.
Security reference: OAuth 2.0 Security Best Current Practice (RFC 9700).