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. Vouched KYA supports multiple authentication methods that determine how the user proves their identity before granting a delegation.
Prerequisites
- A Vouched KYA 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
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. Vouched KYA creates delegation with verified user identity
6. Agent receives the delegation tokenSupported Providers
Vouched KYA 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.
GitHub's user:email is read-only. It shows which of the account's emails is the verified primary, so a GitHub sign-in links to an existing account only by that email.
Proxy Mode (Client Secret Required)
These providers require a client_secret for the token exchange. Vouched KYA 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.
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. Vouched KYA 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
To refresh the provider's scopes, open its OAuth method in Policy → Auth, card 02 Authentication methods, enter the Client secret again and save: a save that carries the Client ID and secret refreshes that provider's scopes, the ones its API lists or, when it lists none, its documented scopes. The Tools table in the same card shows the scopes each tool declares. The OAuth method's Scopes field sets the scopes an agent's delegation must carry to call the method's tools. It suggests the provider's scopes as you type and accepts any other scope, and its Refresh scopes button refreshes the provider's list without a save. A save that changes a method's scopes lists each change, for example "Adds orders:write to 3 tools", and asks you to confirm.
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. Vouched KYA sends credentials to your auth endpoint
5. Your backend validates and returns a session token
6. Vouched KYA 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:
Response Field Mapping
Map your auth endpoint's response fields to Vouched KYA'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
Authorizationheader - Custom header: Sent in a custom header of your choice
PKCE Auto-Discovery
If your custom provider supports OAuth 2.0, Vouched KYA 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. Vouched KYA 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:
How Authorization Mode Is Determined
Vouched KYA 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