Developers

MCP OAuth (Management Users)

2 min read

Use OAuth when your MCP client needs delegated management-user access without storing long-lived management tokens.

Why OAuth for MCP

OAuth gives each external client scoped, revocable access:

  • short-lived access tokens
  • refresh token rotation
  • per-client scope controls
  • centralized revocation and audit logging

For MCP-first rollouts, use the scopes below:

  • mcp:tools:read
  • mcp:tools:write

High-level flow (PKCE)

  1. Create an OAuth client with allowed redirect URIs and scopes.
  2. Sign in as a management user.
  3. Request an authorization code with PKCE (code_challenge).
  4. Exchange the code + code_verifier for access/refresh tokens.
  5. Call AI/MCP endpoints with Authorization: Bearer <access-token>.
  6. Refresh when access token expires.

Create OAuth client

POST /v1/oauth/clients

Use an admin management user and include:

  • name
  • organizationId
  • redirectUris
  • allowedScopes
  • isConfidential

Authorize and exchange

Authorization code:

POST /v1/oauth/authorize

Required fields:

  • responseType: "code"
  • clientId
  • organizationId
  • redirectUri
  • scope
  • codeChallenge
  • codeChallengeMethod: "S256"

Token exchange:

POST /v1/oauth/token

Grant type authorization_code requires:

  • clientId
  • code
  • redirectUri
  • codeVerifier

Grant type refresh_token requires:

  • clientId
  • refreshToken

Use token with AI/MCP endpoints

Send this header:

  • Authorization: Bearer <oauth-access-token>

When OAuth scope enforcement is enabled, AI/MCP routes require matching scopes.

Revoke and introspect

  • Revoke token: POST /v1/oauth/revoke
  • Introspect token: POST /v1/oauth/introspect

Use revocation for client offboarding, leaked tokens, or emergency access removal.

Security guidance

  • Always use PKCE (S256) for public clients.
  • Keep redirect URI allowlists strict and exact.
  • Prefer confidential clients for server-side apps.
  • Rotate client secrets and monitor audit events.
  • Use least-privilege scopes per client.

Related docs