Authentication

Four ways to authenticate with the Velocity API.

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-workspace

Workspace 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

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-workspace

Personal 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. Without the header, only user-level operations (like listing workspaces or reading your profile) are available.

Personal Key Scopes

OAuth 2.0

For third-party applications, use OAuth 2.0 with PKCE. Register an OAuth app from Settings → OAuth Apps to get a client ID and secret.

Authorization Flow

GET https://velocity.quest/oauth/consent
  ?client_id=your_client_id
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=issues:read issues:write
  &state=random_state
  &code_challenge=your_challenge
  &code_challenge_method=S256

POST https://velocity.quest/api/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "auth_code_from_callback",
  "redirect_uri": "https://yourapp.com/callback",
  "client_id": "your_client_id",
  "code_verifier": "your_verifier"
}

Authorization: Bearer access_token_here

Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to get a new one:

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"
}

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.