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:readmcp:tools:write
High-level flow (PKCE)
- Create an OAuth client with allowed redirect URIs and scopes.
- Sign in as a management user.
- Request an authorization code with PKCE (
code_challenge). - Exchange the code +
code_verifierfor access/refresh tokens. - Call AI/MCP endpoints with
Authorization: Bearer <access-token>. - Refresh when access token expires.
Create OAuth client
POST /v1/oauth/clients
Use an admin management user and include:
nameorganizationIdredirectUrisallowedScopesisConfidential
Authorize and exchange
Authorization code:
POST /v1/oauth/authorize
Required fields:
responseType: "code"clientIdorganizationIdredirectUriscopecodeChallengecodeChallengeMethod: "S256"
Token exchange:
POST /v1/oauth/token
Grant type authorization_code requires:
clientIdcoderedirectUricodeVerifier
Grant type refresh_token requires:
clientIdrefreshToken
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.