Authentication

Three ways to authenticate with the Velocity API.

API Keys

API keys are the simplest way to authenticate. 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

API 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.

Available 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://app.velocity.dev/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://app.velocity.dev/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://app.velocity.dev/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.