Authentication
Choose credentials for GraphQL, external-service APIs or MCP.
GraphQL API keys and external-service OAuth applications are available on every plan. MCP requires Pro, Business or Enterprise and current workspace membership. Product features and role checks still apply after authentication.
Workspace API Keys
Workspace API keys grant access to a single workspace's resources. Create a key from Settings → API Keys, then include it in the Authorization header:
Authorization: Bearer vel_your_api_key_here
X-Workspace-Slug: your-workspaceWorkspace keys are prefixed with vel_ and stored as SHA-256 hashes. The full key is displayed only once at creation time. Each key has scoped permissions — you can create read-only or read-write keys. The workspace is automatically resolved from the key, but you can also pass X-Workspace-Slug to be explicit.
Workspace Key Scopes
| Scope | Description |
|---|---|
read:issues | Read issues and comments |
write:issues | Create and modify issues and comments |
read:projects | Read projects |
write:projects | Create and modify projects |
read:teams | Read teams and workflows |
write:teams | Modify teams and workflows |
read:workspaces | Read workspace resources |
write:workspaces | Modify workspace resources |
read:users | Read users |
admin | Full workspace API access, subject to membership permissions |
For ordinary GraphQL API keys, scopes currently enforce read versus write access at the operation level; the resource names in the scope picker do not provide per-resource isolation. Use the external-service OAuth capability setwhen an integration needs resource-specific delegated permissions.
Personal API Keys
Personal API keys are user-level keys that work across all workspaces you belong to. Create a key from Settings → Account → Personal API Keys:
Authorization: Bearer velu_your_personal_key_here
X-Workspace-Slug: target-workspacePersonal keys are prefixed with velu_ (note the ufor “user”). Unlike workspace keys, they do not auto-resolve a workspace — pass the X-Workspace-Slug header to target a specific workspace context. Workspace operations must also supply any IDs required by their GraphQL fields. The header does not expand your membership or the credential's permissions.
Personal keys also authenticate the automation API used by Make, which names the workspace with a workspaceId parameter instead of this header.
Personal Key Scopes
| Scope | Description |
|---|---|
user:read | Read your own profile |
user:write | Update your own profile |
workspaces:list | List workspaces you belong to |
workspaces:create | Create new workspaces |
workspaces:update | Update workspace settings |
workspaces:delete | Delete workspaces |
admin | Full user-level access |
Use workspace keys (vel_) for automations and integrations that only need access to one workspace. Use personal keys (velu_) for CLI tools, scripts, or applications that need to operate across multiple workspaces or manage your user profile.
OAuth 2.0 for External Services
Use OAuth when customers connect your service to Velocity. Register an External service in Settings → OAuth Apps. Your workspace owns the application; customers explicitly approve its scopes and one or more of their own workspaces. They do not need to join your workspace or share a personal API key.
External apps use authorization codes with PKCE S256 and browser-bound state. Confidential services also authenticate with a client secret; public clients use PKCE without a secret. The resulting tokens can call the documented GraphQL capability set and /api/v1/identity and issue REST endpoints. Scope and current workspace permissions apply to every request. Users can revoke connections in Settings → OAuth Apps → Your connected applications.
Follow Connect Velocity with OAuth for setup, callback validation, permissions, refresh/revocation, rate limits and a runnable external-service example. These API grants use scopes such as read:issues and write:issues; they do not authenticate MCP or automation API calls.
OAuth for MCP Clients
MCP clients discover the authorization server and register dynamically with POST /api/oauth/register. Public native clients use PKCE S256 and token_endpoint_auth_method: none, without a client secret. The user selects one eligible workspace during consent. Supported MCP scopes are mcp:read mcp:write. Use the MCP setup guidefor client configuration. For general API integrations, use the API credentials above and their documented permissions.
Authorization Flow
Redirect to authorize
GET https://velocity.quest/api/oauth/authorize
?client_id=your_client_id
&redirect_uri=http://127.0.0.1:53682/callback
&response_type=code
&scope=mcp:read%20mcp:write
&state=random_state
&code_challenge=base64url_sha256_of_verifier
&code_challenge_method=S256Exchange code for tokens
POST https://velocity.quest/api/oauth/token
Content-Type: application/json
{
"grant_type": "authorization_code",
"code": "auth_code_from_callback",
"redirect_uri": "http://127.0.0.1:53682/callback",
"client_id": "your_client_id",
"code_verifier": "your_verifier"
}Use the access token with /api/mcp
Authorization: Bearer access_token_hereRefreshing Tokens
Access tokens expire after 1 hour. Refresh tokens expire after 90 days without successful rotation. Save both replacement tokens after each refresh and serialize refresh requests; public-client replay revokes the grant. After expiry or revocation, sign in again. Use the refresh token to get a new pair:
POST https://velocity.quest/api/oauth/token
Content-Type: application/json
{
"grant_type": "refresh_token",
"refresh_token": "your_refresh_token",
"client_id": "your_client_id"
}MCP credentials can also use the private attachment API with the same MCP scopes, live consent and plan checks. This resource-specific access does not grant permission to unrelated REST routes.
Session Tokens
The web application uses Supabase session tokens (JWTs) passed in the Authorization header. This method is used internally by the Velocity web client and is not recommended for external integrations.
Use workspace API keys for single-workspace integrations. Use personal API keys for cross-workspace tools and scripts. Use OAuth 2.0 for third-party applications that act on behalf of users.