Workload Token Exchange

POST https://{tenant-slug}.knoxcall.com/v1/oauth/token

Exchange a workload’s OIDC id_token — a GitHub Actions token, a GCP or AWS workload identity token, an Azure managed-identity token — for a short-lived KnoxCall phantom token, using RFC 8693 token exchange. Nothing long-lived is stored in the pipeline.

This is not the OAuth 2.1 token endpoint. POST https://api.knoxcall.com/oauth/token mints management-API access tokens for /v1/*. This endpoint lives on your tenant’s data-plane subdomain under /v1/oauth/token, and mints phantom tokens for /v1/ai/<agent> and /v1/mcp/<slug>. The two are separate endpoints with separate credentials.

The endpoint is unauthenticated by design — the subject token is the credential, and verifying it is what the endpoint is being asked to do. Prerequisite: an OIDC binding An exchange only succeeds against a binding you have configured (the agent’s Federation section, or the admin API). A binding pins:

the trusted issuer, whose JWKS is fetched over HTTPS from its published discovery document;
the required attribute conditions — for example a specific repository, ref or environment;
the capability scope and TTL of the token that gets minted.

A binding with zero attribute conditions is refused. A binding that matched any token from an issuer would hand a KnoxCall credential to every repository on GitHub. Request application/x-www-form-urlencoded (JSON is also accepted).

POST /v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<oidc_id_token>
&subject_token_type=urn:ietf:params:oauth:token-type:id_token

Field	Required	Notes
`grant_type`	yes	Must be `urn:ietf:params:oauth:grant-type:token-exchange`.
`subject_token`	yes	The workload’s OIDC id_token (a compact JWS).
`subject_token_type`	yes	Must be `urn:ietf:params:oauth:token-type:id_token`.
`audience`	no	Defaults to KnoxCall’s own audience; any other value is refused.
`resource`	no	RFC 8707 resource indicator — an MCP resource URI on this host, e.g. `https://acme.knoxcall.com/v1/mcp/weather`. A single string only; an array or object is refused rather than silently dropped.

Response

{
  "access_token": "kp_live_a_...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "{\"models\":[\"claude-sonnet-*\"]}"
}

expires_in is the binding’s access_token_ttl_seconds, default 900. scope is a JSON serialisation for visibility only — the enforceable copy is bound into the token’s capability HMAC and cannot be edited after minting. What resource changes

Called with	Token kind	Where it works
no `resource`	`agent`	`/v1/ai/<agent>`
a `resource`	`tool`	only the named `/v1/mcp/<slug>`

A resource-bound token is confined to exactly that MCP server: the canonical resource URI is bound into the capability scope, so the HMAC covers it. The MCP plane requires a tool-kind token, and the AI plane refuses a token with no agent — so the kind narrows to match what you asked for, and never widens. Single use A given subject_token can be exchanged once. A replay returns invalid_grant, which is what stops a leaked CI log from being worth anything. Errors RFC 6749-shaped: { "error": "...", "error_description": "..." }.

`error`	Cause
`unsupported_grant_type`	`grant_type` is not the token-exchange URN.
`invalid_request`	Missing or malformed `subject_token`, wrong `subject_token_type`, or a subject token that is not a JWS triple.
`invalid_target`	Unsupported `audience`, or a `resource` that is not a valid MCP resource URI on this host.
`invalid_grant`	Signature verification failed, the token is expired or not yet valid, no enabled binding matches its issuer and attributes, or the subject token has already been exchanged.
`server_error`	Issuer JWKS unreachable, or the tenant master key is unavailable.

Rate limits 30 requests/minute per (client IP, issuer, subject) and 60/minute per client IP. The client IP is deliberately part of the subject bucket: iss and sub come from an unverified JWT and are public for the primary use case, so keying on the claims alone would let anyone who knows your repository name lock out your real CI runs. See Limits. Example — GitHub Actions

permissions:
  id-token: write
steps:
  - name: Exchange for a KnoxCall phantom token
    run: |
      OIDC=$(curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
        "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=knoxcall" | jq -r .value)

      KC=$(curl -s -X POST https://acme.knoxcall.com/v1/oauth/token \
        -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
        -d subject_token="$OIDC" \
        -d subject_token_type=urn:ietf:params:oauth:token-type:id_token \
        | jq -r .access_token)

      curl https://acme.knoxcall.com/v1/ai/support-bot/v1/messages \
        -H "Authorization: Bearer $KC" \
        -H "content-type: application/json" \
        -d '{"model":"claude-sonnet-5","max_tokens":64,"messages":[{"role":"user","content":"hi"}]}'

See Tokens & DPoP for the conceptual overview.

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Changelog

Workload Token Exchange

Workload token exchange

​Workload token exchange

Workload token exchange