OAuth Integration

Overview

Checkpoint supports standard OAuth 2.0 flows for MCP-I (Model Context Protocol with Identity) agent authorization. When an AI agent needs access to a user's resources, it initiates an OAuth flow. The user sees a consent page, approves the request, and Checkpoint creates a delegation with the granted scopes.

OAuth Flow

1. AI Agent → Authorization Request → Checkpoint
2. Checkpoint → Consent Page → User
3. User approves → Checkpoint creates delegation
4. Checkpoint → Authorization Code → AI Agent (via callback)
5. AI Agent → Token Exchange → Checkpoint
6. Checkpoint → Access Token + Delegation Reference → AI Agent
7. AI Agent uses delegation reference in MCP-I proofs

Authorization Endpoint

The agent initiates the flow by directing the user to the authorization URL:

https://kya.vouched.id/api/v1/bouncer/authorize?
  response_type=code
  &client_id={agent_did}
  &redirect_uri={callback_url}
  &scope=files:read+files:write
  &state={random_state}
  &code_challenge={pkce_challenge}
  &code_challenge_method=S256

Parameters

Callback Handling

After the user approves, Checkpoint redirects to the redirect_uri with an authorization code:

https://agent.example.com/callback?
  code=auth_code_xyz
  &state={random_state}

The agent's callback handler at /api/v1/bouncer/oauth/callback processes the response and initiates the token exchange.

Token Exchange

Exchange the authorization code for an access token:

curl -X POST https://kya.vouched.id/api/v1/bouncer/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "auth_code_xyz",
    "redirect_uri": "https://agent.example.com/callback",
    "client_id": "did:key:z6Mk...",
    "code_verifier": "original_pkce_verifier"
  }'

Response:

{
  "access_token": "tok_abc123",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "ref_xyz789",
  "delegation_id": "del_abc123",
  "scope": "files:read files:write"
}

The delegation_id is used by the agent when creating MCP-I proofs (as the delegationRef field).

Refresh Tokens

When the access token expires, use the refresh token to obtain a new one:

curl -X POST https://kya.vouched.id/api/v1/bouncer/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "ref_xyz789",
    "client_id": "did:key:z6Mk..."
  }'

Provider Configuration

Configure OAuth settings in the Checkpoint dashboard:

1. Navigate to Project → Control Access → Config
2. Set allowed redirect URIs
3. Configure token lifetimes
4. Enable or disable specific scopes

You can also manage provider configuration via the API:

curl -X GET https://kya.vouched.id/api/v1/bouncer/projects/{projectId}/providers \
  -H "X-API-Key: $CHECKPOINT_API_KEY"

Supported OAuth Providers

Checkpoint includes pre-configured support for these providers:

Direct Mode (PKCE-Supported)

These providers support PKCE, so no client secret is required:

Proxy Mode (Client Secret Required)

These providers require a client secret. Checkpoint keeps the secret server-side:

You can also configure custom OAuth providers. See Authentication Methods for details on all supported authentication modes.

Security Considerations

PKCE Requirement

All authorization requests must use PKCE with S256 method. This is mandatory, not optional. Requests without a valid code_challenge will be rejected.

State Parameter

Always include a cryptographically random state parameter and verify it in the callback. This prevents CSRF attacks.

Redirect URI Validation

Only pre-registered redirect URIs are accepted. Register your callback URLs in the dashboard under Project → Control Access → Config.

Token Storage

Agents should store access tokens and refresh tokens securely. Never expose tokens in client-side code or logs.

Next Steps

• Authentication Methods — Compare OAuth with other auth options
• Consent Flows — Customize the consent page users see
• Managing Delegations — The delegations OAuth creates
• Tool Protection — Map OAuth scopes to tools