Skip to main content

​
Initiate OAuth login

GET /api/auth/:provider/login?userId=<userId>
Redirects the user’s browser to the OAuth provider’s authorization page with the appropriate scopes.
ParameterInRequiredDescription
providerpathYesOAuth provider: github, google, slack, or linear
userIdqueryYesThe user ID to associate with the connection
Response: HTTP 302 redirect to the provider’s authorization URL. The server generates a random state parameter (10-minute TTL) and stores a pending OAuth entry with the user’s ID, provider, PKCE verifier (if applicable), and requested scopes.

​
OAuth callback

GET /api/auth/:provider/callback
Handles the OAuth redirect after the user authorizes. Exchanges the authorization code for tokens, encrypts them, and stores them.
ParameterInRequiredDescription
providerpathYesOAuth provider
codequeryYesAuthorization code from the provider
statequeryYesState parameter for CSRF protection
Success response (200): 
{
  "success": true,
  "provider": "github",
  "userId": "user-123",
  "scopes": ["repo", "read:user"]
}
Error response (400): 
{
  "error": "access_denied",
  "error_description": "The user denied the request"
}

​
Disconnect provider

DELETE /api/auth/:provider?userId=<userId>
Revokes tokens (best-effort) and deletes stored credentials for the provider.
ParameterInRequiredDescription
providerpathYesOAuth provider
userIdqueryYesUser ID
Response (200): 
{
  "disconnected": true,
  "provider": "github",
  "userId": "user-123"
}

​
List connections

GET /api/auth/connections?userId=<userId>
Lists which OAuth providers a user has connected.
ParameterInRequiredDescription
userIdqueryYesUser ID
Response (200): 
{
  "userId": "user-123",
  "providers": ["github", "google"]
}