Authentication Methods

Overview

When an AI agent requests access to a user's resources, the user must authenticate and consent. Checkpoint supports multiple authentication methods that determine how the user proves their identity before granting a delegation.

Method Comparison

Consent Only

The simplest method. Users see a consent page showing the agent's identity and requested permissions, then click Allow or Deny. No external authentication is required.

How It Works

1. Agent requests delegation
2. User sees consent page with:
   - Agent name and identity
   - Requested permissions (scopes)
   - Terms acceptance
   - Expiration notice
3. User clicks "Allow"
4. Delegation is created

When to Use

• Internal or first-party agents where trust is already established
• Low-risk operations (read-only, informational queries)
• Prototyping and development
• Situations where adding OAuth would be unnecessary friction

Configuration

In the dashboard, navigate to Project → Control Access → Consent and select Consent Only as the authorization mode. No provider configuration is needed.

OAuth

Users authenticate via a third-party OAuth provider (GitHub, Google, etc.) before granting the delegation. This verifies the user's identity through a trusted external service.

How It Works

1. Agent requests delegation
2. User is redirected to OAuth provider (e.g., GitHub)
3. User signs in and authorizes
4. Provider returns authorization code
5. Checkpoint creates delegation with verified user identity
6. Agent receives delegation reference

Supported Providers

Checkpoint supports two categories of OAuth providers based on their PKCE capability:

Direct Mode (PKCE-Supported)

These providers support PKCE (Proof Key for Code Exchange), which means the client secret is not required for the authorization flow. This is more secure for client-side applications.

Proxy Mode (Client Secret Required)

These providers do not support PKCE and require a client_secret for the token exchange. Checkpoint acts as a secure proxy, keeping the secret server-side so it's never exposed to the client.

Setup

1. Register an OAuth application with your chosen provider
2. In the dashboard, navigate to Project → Control Access → Config
3. Select the provider and enter your Client ID and Client Secret (if required)
4. Configure allowed redirect URIs
5. Save the configuration

See OAuth Integration for the full OAuth flow details, including authorization endpoints, token exchange, and refresh tokens.

Custom Provider

Connect your own authentication backend. This lets users sign in with your existing auth system — useful for enterprise SSO, internal identity providers, or any custom authentication flow.

How It Works

1. Agent requests delegation
2. User sees consent page with your custom login form
3. User enters credentials
4. Checkpoint sends credentials to your auth endpoint
5. Your backend validates and returns a session token
6. Checkpoint creates delegation with verified identity

Requirements

To integrate a custom provider, you need a backend endpoint that:

1. Accepts a POST request with user credentials
2. Validates the credentials
3. Returns a session token and user information

Configuration

In the dashboard under Project → Control Access → Config, select Custom Provider and configure:

Response Field Mapping

Map your auth endpoint's response fields to Checkpoint's expected format:

Token Usage

Configure how the session token is used in subsequent requests:

• Cookie — Token stored as a browser cookie
• Bearer token — Sent in the Authorization header
• Custom header — Sent in a custom header of your choice

PKCE Auto-Discovery

If your custom provider supports OAuth 2.0, Checkpoint will automatically check for PKCE support by querying /.well-known/oauth-authorization-server. If PKCE is supported, the more secure direct mode is used automatically.

Credentials

A straightforward username/password form for cases where OAuth isn't suitable. The credentials are sent to your configured authentication endpoint for validation.

How It Works

1. Agent requests delegation
2. User sees a login form (username + password)
3. User enters credentials and submits
4. Checkpoint validates against your auth endpoint
5. Delegation is created on successful authentication

When to Use

• Legacy systems without OAuth support
• API key-based authentication
• Internal tools with simple auth requirements
• Environments where redirect-based OAuth isn't practical

Configuration

This method uses the same custom provider configuration as above — you define an auth endpoint, request template, and response mapping. The difference is in the UI: users see a traditional login form instead of an OAuth button.

Additional UI options:

How Authorization Mode Is Determined

Checkpoint selects the authentication method based on this priority:

1. Tool-specific configuration — If the tool has an explicit authorization.type set, that takes precedence
2. Active provider type — The provider configured for the tool (OAuth, credential, custom)
3. Project default — Falls back to the project's default consent configuration
4. Consent Only — If no providers are configured, defaults to consent-only

This means different tools in the same project can use different authentication methods. For example:

• A read-files tool might use Consent Only (low risk)
• A process-payment tool might require OAuth with GitHub (high risk)
• An internal admin-audit tool might use Credentials (enterprise SSO)

Customizing the Experience

Regardless of which authentication method you choose, you can customize the consent page appearance:

• Application name and logo
• Primary and secondary brand colors
• Title and description text
• Permission descriptions for each scope
• Terms of service and privacy policy links
• Button text and success screen messaging

See Consent Flows for the full customization guide.

Next Steps

• OAuth Integration — Full OAuth flow documentation
• Consent Flows — Customize the consent page
• Tool Protection — Configure per-tool authorization requirements
• Deploying an MCP-I Server — Set up your MCP-I server