Authentication Methods
Choose how users authenticate when authorizing AI agents
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.
Prerequisites
- A Checkpoint project. See Credentials for how to find your Project ID and API key in Installations.
- Access to the dashboard's Policy → Auth page (
/dashboard/{orgId}/{projectId}/policy/auth), where every method below is configured.
Method Comparison
| Method | User Experience | Identity Verification | Best For |
|---|---|---|---|
| Consent Only | Click "Allow" | None (trust-based) | First-party agents, low-risk actions |
| OAuth | Sign in with GitHub, Google, etc. | External provider | Third-party agents, user-facing apps |
| Custom Provider | Sign in with your own auth system | Your backend | Enterprise SSO, internal tools |
| Credentials | Username and password form | Your backend | Legacy systems, API key auth |
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 createdWhen 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, open Policy → Auth (/dashboard/{orgId}/{projectId}/policy/auth) and add the Consent only method. No provider configuration is needed.
Even with Consent Only, every delegation is still cryptographically signed and verifiable. The "consent only" label refers to the user authentication step, not the security of the delegation itself.
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 the delegation tokenSupported Providers
Checkpoint runs each provider in one of two modes, based on whether the provider's token exchange requires a client secret:
Direct Mode (No Client Secret)
These providers support PKCE (Proof Key for Code Exchange) and don't require a client secret, so the OAuth flow runs directly against the provider. This is more secure for client-side applications.
| Provider | Default Scopes |
|---|---|
| GitHub | repo:read, user:email |
openid, email, profile | |
| Microsoft | User.Read |
| Linear | read |
| Auth0 | openid, profile, email |
Proxy Mode (Client Secret Required)
These providers 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 browser or the agent. Apple and Discord support PKCE but still require a client secret, which is why they run in proxy mode.
| Provider | Default Scopes |
|---|---|
| Apple | name, email |
| Discord | identify, email |
r_liteprofile, r_emailaddress | |
| Slack | channels:read |
| Notion | read |
| Stripe | read_only |
| Shopify | read_products |
For proxy mode providers, you must provide a client secret in the dashboard configuration. The
secret stays server-side and is never returned by any API — provider reads carry only a
hasClientSecret flag. Checkpoint performs the token exchange itself (proxy mode), or syncs the
secret to your gateway worker as a Cloudflare secret at deploy time.
Setup
- Register an OAuth application with your chosen provider
- In the dashboard, open Policy → Auth (
/dashboard/{orgId}/{projectId}/policy/auth) and add an OAuth method - Enter the Client ID, Client secret, Redirect URI, and the provider's authorization and token endpoints
- Save the configuration
Per-tool OAuth scope display and scope refresh for already-connected tools still live on the legacy Control Access surface (legacy surface: /dashboard/{orgId}/{projectId}/control-access).
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 identityRequirements
To integrate a custom provider, you need a backend endpoint that:
- Accepts a POST request with user credentials
- Validates the credentials
- Returns a session token and user information
Configuration
In the dashboard under Policy → Auth, add a Credentials method (this is the custom-provider configuration) and configure:
| Field | Required | Description |
|---|---|---|
| Provider ID | Yes | Unique identifier (e.g., my-company-auth) |
| Display name | No | Name shown on the consent screen |
| Auth endpoint | Yes | Your backend URL that handles login |
| Identity field | Yes | Request field that carries the username/identifier |
| Password field | Yes | Request field that carries the password |
| Session token | Yes | How Checkpoint reads your session: Session cookies (cookie name) or JSON path into your response |
Response Field Mapping
Map your auth endpoint's response fields to Checkpoint's expected format:
| Checkpoint Field | Your Response Field | Purpose |
|---|---|---|
| Session token | Configurable (e.g., data.token) | Used for subsequent API calls |
| User ID | Configurable (e.g., data.user.id) | Linked to delegation |
| User email | Configurable (e.g., data.user.email) | Display in dashboard |
| User display name | Configurable (e.g., data.user.name) | Display in consent |
| Token expiration | Configurable (e.g., data.expiresAt) | Token refresh timing |
Token Usage
Configure how the session token is used in subsequent requests:
- Cookie — Token stored as a browser cookie
- Bearer token — Sent in the
Authorizationheader - Custom header — Sent in a custom header of your choice
PKCE Auto-Discovery
If your custom provider supports OAuth 2.0, Checkpoint can check for PKCE support by querying the provider's discovery metadata — /.well-known/openid-configuration first, then /.well-known/oauth-authorization-server — and looking for S256 in code_challenge_methods_supported. 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 authenticationWhen 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:
| Option | Default | Description |
|---|---|---|
| Username label | "Username" | Custom label for the username field |
| Password label | "Password" | Custom label for the password field |
| Show "Remember me" | false | Adds a remember-me checkbox |
| Show "Forgot password" | false | Adds a forgot password link |
| Forgot password URL | — | Link destination for forgot password |
How Authorization Mode Is Determined
Checkpoint selects the authentication method based on this priority:
- Tool-specific configuration — If the tool has an explicit
authorization.typeset, that takes precedence - Active provider type — The provider configured for the tool (OAuth, credential, custom)
- Project default — Falls back to the project's default consent configuration
- 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-filestool might use Consent Only (low risk) - A
process-paymenttool might require OAuth with GitHub (high risk) - An internal
admin-audittool 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 a KYA-OS Server — Set up your KYA-OS server