OAuth Integration

Integrate OAuth flows with KYA-OS for AI agent authorization

Overview

Vouched KYA exposes two OAuth-shaped surfaces, and they solve different problems:

  • Gateway OAuth 2.1 (/oauth/{orgSlug}/*): one standards-compliant OAuth 2.1 authorization server per organization, with mandatory PKCE and rotating refresh tokens. MCP clients (Claude Desktop, Cursor, VS Code) use it to connect to gateway-protected MCP servers.
  • Bouncer delegation flow (/api/v1/bouncer/*): the consent flow that turns an agent's scope request into a delegation. The user authenticates (optionally through an upstream OAuth provider like GitHub or Google) on a consent page and approves; Vouched KYA mints a delegation token. These endpoints are delegation-specific: they deliberately do not implement the OAuth 2.1 parameter set.

If you are wiring an MCP client to a protected server, use the gateway endpoints. If you are building an agent that needs user-approved scopes, use the delegation flow.

Prerequisites

  • A Vouched KYA project. See Credentials for how to find your Project ID and API key in Installations.
  • For the delegation flow's OAuth mode: an upstream OAuth provider app (GitHub, Google, etc.) registered with its callback URL pointed at /api/v1/bouncer/oauth/callback: see Provider Configuration below.

Gateway OAuth 2.1

Issuer and Discovery

Each organization has one authorization server. Its issuer is https://kya.vouched.id/oauth/{orgSlug}, or https://auth.{domain}/oauth/{orgSlug} when the organization has a verified custom domain. An organization has exactly one issuer: the other URL returns 404.

MCP clients find the issuer in the protected resource's metadata (RFC 9728) and then read the authorization server metadata (RFC 8414). The same document is served at all four discovery URLs clients probe:

Discovery URLForm
/.well-known/oauth-authorization-server/oauth/{orgSlug}RFC 8414 path insertion
/.well-known/openid-configuration/oauth/{orgSlug}OpenID path insertion
/oauth/{orgSlug}/.well-known/oauth-authorization-serverRFC 8414 appended
/oauth/{orgSlug}/.well-known/openid-configurationOpenID appended
Metadata fieldValue
authorization_endpoint{issuer}/authorize
token_endpoint{issuer}/token
registration_endpoint{issuer}/register
jwks_uri{issuer origin}/orgs/{orgSlug}/jwks.json

The jwks_uri key set publishes the organization's signing key under the kid its access tokens carry.

Authorization Endpoint

The client starts the flow by sending the user's browser to:

https://kya.vouched.id/oauth/{orgSlug}/authorize?
  response_type=code
  &client_id={client_id}
  &redirect_uri={callback_url}
  &state={random_state}
  &code_challenge={pkce_challenge}
  &code_challenge_method=S256
  &scope=mcp

Vouched KYA signs the user in (redirecting to /signin when there is no session) and checks they belong to the organization, then redirects to the consent page, /consent/{requestId}. Organizations configured for merchant sign-in, and projects whose consent policy names a sign-in method the consent page offers, skip the platform session and sign the person in on the consent page instead. Approving consent creates the delegation, issues the authorization code, and redirects back to your redirect_uri with code and state.

Step-up

When a resource answers insufficient_scope, the client sends the person back through authorize with the wider scope. The person is not asked to sign in again, and only the assurance they do not yet hold is asked for (a registry number never satisfies a name match). The new credential carries every scope of the previous grant that policy still allows, plus the new ones, and replaces it: the previous credential stops working and its refresh tokens are revoked, so there is one live credential per grant.

Amount limits

A client can ask for a per-call spending limit with RFC 9396 authorization_details. The value is a JSON array with exactly one entry of type kya-os.crisp, and each of its scopes (1 to 7) carries a maxAmount. A credential carries at most 8 CRISP scope entries, and one is kept for a budget the resource's consent policy may set:

[
  {
    "type": "kya-os.crisp",
    "scopes": [
      {
        "resource": "payments:send",
        "matcher": "exact",
        "maxAmount": { "value": "50.00", "currency": "USD" }
      }
    ]
  }
]
  • resource is a resource:action scope or a URL, with no whitespace anywhere in it. matcher is exact or prefix (regex is refused).
  • value is a decimal string greater than zero, with at most 18 integer and 8 fraction digits, no sign and no exponent. currency is an ISO 4217 code in upper case. Amounts are never converted between currencies.

The consent page lists each limit in plain words, for example "Up to $50.00 per call for payments:send", and says that a limit applies only to tools that report an amount. The credential the approval mints carries the limits as constraints.crisp.scopes[].maxAmount, and so does every access token issued from it. The gateway then refuses a tools/call over the limit, in another currency, or without a readable amount, on tools whose amount setting names the argument that holds the amount. A tool without that setting is not checked.

A step-up keeps the limits of the grant it replaces: the consent page lists them as kept from the earlier approval, and the new credential carries them with the ones the new request asks for. Every matching limit applies, so the lowest one wins. If that earlier grant expires, is revoked or is joined by another while the page is open, Allow grants nothing and the page asks the person to review it again. A step-up whose kept and new limits, with a budget, would need more than 8 CRISP entries is refused at approval.

A malformed value, a budget, a regex matcher, a resource with whitespace, a limit of zero, a lower-case currency, more than 7 limits, more than one entry, or another type is refused with invalid_authorization_details at your redirect_uri, with the request's state, once the redirect_uri is bound to the client. Nothing is opened or granted.

Limits a project sets

Most clients send no authorization_details, so a project can set the limit itself. In the project's consent policy, a scope entry, or each preset of a scope with presets, takes a maxAmount. Every grant of that scope then carries the limit, whether or not the client asked for one:

{
  "units": { "BNS": { "singular": "Bean", "plural": "Beans" } },
  "scopes": {
    "order:card": {
      "signIn": ["credentials"],
      "assurance": [],
      "maxGrantSeconds": 86400,
      "maxAmount": { "value": "15.00", "currency": "USD" },
      "maxAmountPer": "order"
    },
    "order:beans": {
      "signIn": ["credentials"],
      "assurance": [],
      "maxGrantSeconds": 86400,
      "maxAmount": { "value": "150", "currency": "BNS" },
      "maxAmountPer": "order"
    },
    "card:reload": {
      "signIn": ["credentials"],
      "assurance": [],
      "maxGrantSeconds": 86400,
      "maxAmount": { "value": "25.00", "currency": "USD" },
      "maxAmountPer": "reload"
    }
  }
}
  • maxAmount.value follows the same rules as a client's limit. maxAmount.currency is an ISO 4217 code, or a code named in units.
  • units names a code that is not a currency: BNS above reads "150 Beans", never "BNS 150.00". A named unit counts whole numbers, so "150.50" is refused. An ISO 4217 code keeps its own name.
  • maxAmountPer is the word after "per" on the consent page ("Up to $15.00 per order"). It is optional, reads "call" when left out, and changes only the words: every limit is checked per call.
  • A limit does not make a scope grantable. The scope must already be one the project can grant.

The consent page shows the limit on the permission's row. The credential carries it the way it carries a client's limit, as { "resource": "order:card", "matcher": "exact", "maxAmount": { "value": "15.00", "currency": "USD" } } in constraints.crisp.scopes[], and only for the scopes the person approves. The same amount setting rule applies: a tool without one is not checked. Every limit that matches a tool applies, so a tool that requires two scopes limited in different units refuses every call.

When the client also sends a limit for the same scope:

  • Same currency: the lower of the two is the one the grant carries. A project limit never loosens a client's limit, and a client cannot raise a project's.
  • Different currencies: the consent page shows both limits, and Allow refuses the approval and grants nothing, because the two cannot be compared.
  • A prefix limit that covers the scope: in the same currency, both stay on the grant, and the lowest applies at call time. In another currency, Allow refuses as above.

A project limit counts toward the 8 CRISP entries of a credential, so an approval of more limited scopes than that is refused. A change to a project's limit applies to consents approved afterwards. Delegations already granted keep the limit they were minted with.

Project limits apply to grants approved on the consent page, on either rail. They do not reach a delegation created any other way: POST /api/v1/bouncer/delegations, POST /api/v1/bouncer/projects/{projectId}/delegations and the Bouncer OAuth callback mint without them.

On the gateway, a limit binds only a grant that holds the scope. In observe mode the gateway does not check a tool's required scopes against the grant, so a grant without the limited scope reaches the tool with no limit.

Parameters

ParameterRequiredDescription
response_typeYesMust be code
client_idYesOpaque ID from dynamic client registration, or an HTTPS Client ID Metadata Document (CIMD) URL
redirect_uriYesHTTPS URL, loopback HTTP, or a native-app private-use scheme such as cursor:// or claude:// (RFC 8252 §§7.1–7.3)
stateYesRandom value for CSRF protection: requests without it are rejected
code_challengeYesPKCE challenge (base64url of the SHA-256 of the verifier)
code_challenge_methodYesMust be S256: plain PKCE is rejected
scopeNoSpace-separated scope identifiers (up to 16). Defaults to mcp
authorization_detailsNoPer-call amount limits (RFC 9396), as described in Amount limits

PKCE (Proof Key for Code Exchange) is required for all gateway authorization requests, and only the S256 method is accepted. Validation errors redirect to your registered redirect_uri with ?error=...&state=... only after Vouched KYA verifies the client and callback. Before that, errors end on the organization's branded page and never redirect: an unknown opaque client gets 400 "Reconnect this app" (remove the connector and add it again), and a registration lookup outage gets 503; retry later.

Opaque client IDs must come from POST /oauth/{orgSlug}/register (RFC 7591 dynamic client registration). Use the returned client_id after the endpoint returns 201. Registration must persist successfully before Vouched KYA issues the ID. A persistence failure returns 500 server_error; retry registration later.

Vouched KYA validates redirect_uri against the registration on authorization and consent requests. Loopback callbacks can use an ephemeral port and any supported loopback host (RFC 8252). Their scheme, path, and query must match the registered callback. An HTTPS CIMD client ID uses its verified metadata document instead of dynamic registration.

Token Exchange

Exchange the authorization code for tokens. The body must be application/x-www-form-urlencoded (JSON bodies are rejected):

curl -X POST https://kya.vouched.id/oauth/{orgSlug}/token \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=auth_code_xyz" \
  --data-urlencode "redirect_uri=https://agent.example.com/callback" \
  --data-urlencode "client_id={client_id}" \
  --data-urlencode "code_verifier={original_pkce_verifier}"

Response:

{
  "access_token": "eyJhbGciOiJFZERTQSIs...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "b64url_random_token",
  "scope": "mcp"
}

The access token is a KYA-OS delegation VC-JWT (a W3C Verifiable Credential in JWT form) minted under the issuing organization's DID, so the gateway can verify it without a database lookup. A code or refresh token issued by another organization's authorization server fails with invalid_grant. Authorization codes are single-use: a replayed, expired, or mismatched code fails with invalid_grant, as does a code_verifier that does not hash to the original code_challenge. The verifier must be 43–128 characters (RFC 7636 §4.1).

Refresh Tokens

Access tokens live 15 minutes, or less when the delegation expires sooner (expires_in gives the actual lifetime). Use the refresh token to obtain a new one:

curl -X POST https://kya.vouched.id/oauth/{orgSlug}/token \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token={refresh_token}" \
  --data-urlencode "client_id={client_id}"

Every refresh rotates the token: the response carries a new refresh_token and the one you presented is revoked. Replaying an already-used refresh token is treated as theft: all tokens in that delegation's chain are revoked. Refresh tokens expire 30 days after issue, or when the delegation expires, whichever comes first.

Token grants never outlive the delegation. If the underlying delegation has expired, been revoked, or is no longer active, both grant types fail with invalid_grant and the client must start a new authorization flow. A refresh against an expired delegation also revokes every refresh token in its chain.

Changelog

One authorization server per organization (unreleased)

Each organization's OAuth endpoints moved under its issuer, /oauth/{orgSlug}: authorize, token, register and the discovery documents listed above. The issuer's jwks_uri is now /orgs/{orgSlug}/jwks.json, which publishes the key that signs the organization's access tokens.

The previous endpoints are gone, with no redirects: /api/v1/gateway/oauth/authorize, /api/v1/gateway/oauth/authorize/{orgSlug}, /api/v1/gateway/oauth/token, /api/v1/gateway/oauth/register, the /oauth/gateway/{orgSlug} issuer and its discovery documents, the native consent screen (/oauth/gateway/consent/screen, /oauth/gateway/consent/approve, /oauth/gateway/consent/bundle), and the global /.well-known/oauth-authorization-server.

Client registrations and tokens issued under the old endpoints stop working. MCP clients register again on their own when the server answers invalid_client; other clients re-run discovery from the protected resource's metadata and register at the new registration_endpoint.

Amount limits requested with RFC 9396 authorization_details are carried on the consent request, shown on the consent page and minted into the credential, as described in Amount limits. Malformed authorization_details and a requested budget keep their invalid_authorization_details errors.

Limits a project sets (unreleased)

A project can now set a per-call limit on a scope in its consent policy, with named units for codes that are not currencies, as described in Limits a project sets. The consent page and the delegation sheet now write amounts the way people read them: "$50.00", not "USD 50.00". Amounts are still shown exactly as granted, with nothing rounded.

Tokens end with the delegation (unreleased)

Access and refresh tokens now expire no later than the delegation they were issued from. Previously each refresh issued a new 30-day refresh token, so a client could keep refreshing after its delegation had expired. Once the delegation expires, the refresh grant returns 400 invalid_grant (Delegation has expired) and revokes the delegation's refresh tokens. The authorization-code grant does the same for an expired delegation. To keep access, the client starts a new authorization flow.

Opaque client registration required (unreleased)

Authorization now requires a stored registration for every opaque client_id. Fixed client IDs and cached IDs without a stored registration return 400 invalid_client, with no redirect to the callback.

To reconnect an affected client:

  1. Remove its saved OAuth registration, or disconnect the MCP server in the client.
  2. Reconnect the MCP server so the client sends a new request to POST /oauth/{orgSlug}/register.
  3. Save the client_id from the successful 201 response.
  4. Start authorization with that ID and a registered callback URI.

Custom integrations must replace fixed opaque IDs with dynamic registration or a valid HTTPS CIMD client ID. Existing access and refresh tokens keep their current behavior. This change applies when the client next starts authorization. A 503 server_error indicates a temporary service outage. Retry later without clearing the registration.

Bouncer Delegation Flow

The delegation endpoints look OAuth-like (authorize, callback), but they speak delegation vocabulary: the "client" is an agent identified by DID, and the artifact you end up with is a delegation token, not an OAuth access token.

1. Agent → GET/POST /api/v1/bouncer/authorize (agent_did + requested_scopes)
2. Vouched KYA resolves the provider and authorization mode → authorization_url or consent_url
3. User signs in with the upstream provider (OAuth mode) and approves on the consent page
4. Provider redirects to Vouched KYA's callback; Vouched KYA verifies the sign-in and creates the delegation
5. Vouched KYA delivers the delegation token to the project's configured worker URL
6. Agent presents the delegation token on subsequent verification calls

Requesting Authorization

https://kya.vouched.id/api/v1/bouncer/authorize?
  agent_did=did:key:z6Mk...
  &requested_scopes=files:read,files:write
  &expires_in_days=7
  &project_id={projectId}

GET is a user-clickable link (no API key required), so project_id must be passed as a query parameter. POST accepts the same fields as a JSON body and authenticates with your API key instead.

ParameterRequiredDescription
agent_didYesDID of the AI agent requesting authorization
requested_scopesYes1–20 scopes. Comma-separated in the GET query, a JSON array in POST
agent_nameNoHuman-readable name shown on the consent page
expires_in_daysNoDelegation lifetime, 1–365 days (default 7)
session_idNoMCP session ID carried through consent
worker_urlNoHTTPS endpoint that receives the delegation token
providerNoExplicit provider ID (e.g. github, credentials)
tool_nameNoTool whose authorization requirement selects the provider
metadataNoArbitrary JSON carried through the flow
project_idGET onlyRequired when no API key is presented

Response (OAuth provider configured):

{
  "success": true,
  "data": {
    "provider_type": "oauth2",
    "authorization_url": "https://github.com/login/oauth/authorize?...",
    "expires_at": "2026-07-27T12:10:00.000Z",
    "project_id": "proj_abc123",
    "agent_did": "did:key:z6Mk...",
    "requested_scopes": ["files:read", "files:write"]
  },
  "metadata": { "requestId": "req_...", "timestamp": "2026-07-27T12:00:00.000Z" }
}

Send the user to authorization_url within 10 minutes (expires_at). Consent-only projects return provider_type: "none" with a consent_url instead of an authorization URL; credential providers return provider_type: "password" plus the login-form configuration.

Provider selection follows this priority: explicit provider parameter → the tool's authorization requirement (from tool_name or the first scope's tool) → the project's default provider → the first configured provider.

Callback Handling

/api/v1/bouncer/oauth/callback is Vouched KYA's callback for the upstream provider, not the agent's. When you register an OAuth app with a provider (GitHub, Google, …), point its callback URL at this endpoint. The provider redirects back with code and state; Vouched KYA exchanges the code server-side, resolves the signed-in user's identity, and creates the delegation. Agents never implement an OAuth callback handler in this flow.

Delivery to the agent happens out of band: Vouched KYA POSTs a delegation.granted payload (including the delegation_token) to the project's configured worker URL. Delivery is HTTPS-only, and loopback or private-network hosts are refused.

Result Handoff

When the callback has created the delegation, it sends the browser to the consent success page with a one-use oauth_result ticket in the query. The page redeems the ticket once, from the same browser that started the flow, to show the delegation it created:

GET https://kya.vouched.id/api/v1/bouncer/oauth/result?ticket={oauth_result}

Response:

{
  "success": true,
  "data": {
    "delegationId": "a1b2c3d4-...",
    "agentDid": "did:key:z6Mk...",
    "delegationToken": "eyJhbGciOiJFZERTQSJ9...",
    "sessionId": "mcp_session_123"
  }
}

The ticket lives for two minutes and works once, and only with the correlation cookie the flow set in that browser; no credential travels in a URL. The agent itself receives the delegation token through the worker delivery above, not from this endpoint.

There are no refresh tokens in the delegation flow. The delegation token lives as long as the delegation itself (expires_in_days, default 7 days). When it expires, the agent requests a new delegation.

The delegation_token is a W3C VC-JWT signed with EdDSA (Ed25519). KYA-OS servers verify it cryptographically without a database lookup. The delegation_id identifies the delegation in the dashboard and appears as the delegationRef field in KYA-OS proof metadata.

Provider Configuration

Configure authentication methods in the Vouched KYA dashboard at Policy → Auth (/dashboard/{orgId}/{projectId}/policy/auth):

  1. Add an OAuth method and enter the Client ID, Client secret, Redirect URI, and authorization/token endpoints from your provider's OAuth app
  2. Assign an auth method to each tool: which tools require which method, and with which scopes
  3. Customize the consent screen branding and copy

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.

You can also read 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

Vouched KYA includes pre-configured support for GitHub, Google, Microsoft, Linear, and Auth0 in direct (PKCE) mode, and Apple, Discord, LinkedIn, Slack, Notion, Stripe, and Shopify in proxy (client-secret) mode. See Authentication Methods → Supported Providers for the canonical provider/default-scope table: the dashboard configuration forms and the providers API both advertise those same defaults.

Two caveats specific to this flow:

  • Fallback scope drift. The authorize flow keeps its own fallback scope table that doesn't yet cover every provider (and disagrees with GitHub's default): scopes saved in your provider configuration always win, so set them explicitly if the default matters to you.
  • Scope derivation for proxy-mode providers. Default scopes apply only when nothing more specific is available: in practice Vouched KYA derives provider scopes from the delegation's requested tool scopes (for example, user:read maps to GitHub's read:user), and scopes saved in the provider configuration take precedence over both.

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

Security Considerations

PKCE Requirement

All gateway authorization requests must use PKCE with the S256 method: this is mandatory, not optional, and requests without a valid code_challenge are rejected. The bouncer delegation flow does not use PKCE; its authorization codes are instead single-use, short-lived, and bound to the requesting agent's DID and project.

State Parameter

The gateway requires a cryptographically random state parameter and rejects requests without one; verify it in your callback to prevent CSRF. In the delegation flow, Vouched KYA generates and verifies the state itself across the upstream-provider round trip. Agents don't manage it.

Redirect URI Validation

The gateway only accepts redirect URIs in the RFC 8252 shapes listed above (HTTPS, loopback HTTP, or a native app's private-use scheme). For upstream providers in the delegation flow, the redirect URI comes from your provider configuration at Policy → Auth and should point at Vouched KYA's callback endpoint.

Token Storage

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

Next Steps