Token exchange (RFC 8693)

POST

/v1/exchange/token

curl --request POST \
  --url http://localhost:8693/v1/exchange/token \
  --header 'Content-Type: application/json' \
  --data '{ "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange", "subject_token": "eyJhbGciOiJSUzI1NiIs...", "subject_token_type": "urn:ietf:params:oauth:token-type:jwt", "audience": "https://api.target.example.com", "scope": "read:data" }'

• Plaintext (dev mode)
• mTLS (production)

Validates a source credential, evaluates OPA policy, and mints a WIMSE-compliant JWT. Supports execution scoping (DPoP-style), delegation via actor tokens, and capability narrowing.

Protected by mTLS when TLS is enabled.

Request Body ^required

Media type application/json

object

grant_type

required

Must be “urn:ietf:params:oauth:grant-type:token-exchange”

string

Allowed values: urn:ietf:params:oauth:grant-type:token-exchange

subject_token

required

The source credential being exchanged

string

subject_token_type

required

Token type URI identifying the credential format

string

Allowed values: urn:ietf:params:oauth:token-type:jwt urn:starfly:token-type:spiffe-svid urn:starfly:token-type:oidc urn:starfly:token-type:kerberos urn:starfly:token-type:saml urn:starfly:token-type:mtls urn:starfly:token-type:aws-sts urn:starfly:token-type:gcp-wif urn:starfly:token-type:azure-mi urn:ietf:params:oauth:token-type:access_token urn:starfly:token-type:api-key urn:starfly:token-type:agent-mcp urn:starfly:token-type:agent-a2a urn:starfly:token-type:agent-passport

audience

required

Target trust domain or service URL

string

scope

Requested scope

string

actor_token

JWT of the delegating agent (for delegation chains)

string

execution_scope

DPoP-style execution scoping (RFC 9449). Binds the token to a specific HTTP action.

object

htm

HTTP method (e.g., POST, GET)

string

htu

Target URI

string

payload_hash

SHA-256 hash of request body (base64url)

string

nonce

Unique value for replay protection

string

Examples

Kubernetes ServiceAccount

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiIs...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "audience": "https://api.target.example.com",
  "scope": "read:data"
}

SPIFFE SVID

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiIs...",
  "subject_token_type": "urn:starfly:token-type:spiffe-svid",
  "audience": "spiffe://target.example.com"
}

Execution-scoped token (DPoP-style)

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiIs...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "audience": "https://api.example.com",
  "execution_scope": {
    "htm": "POST",
    "htu": "https://api.example.com/v1/transfers",
    "payload_hash": "sha256-abc123",
    "nonce": "unique-nonce-1"
  }
}

Delegation via actor token

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiIs...",
  "subject_token_type": "urn:starfly:token-type:agent-a2a",
  "audience": "https://api.example.com",
  "actor_token": "eyJhbGciOiJSUzI1NiIs..."
}

Responses

200

Exchange succeeded

Media type application/json

object

access_token

required

WIMSE-compliant JWT

string

issued_token_type

required

Always “urn:ietf:params:oauth:token-type:jwt”

string

token_type

required

Always “Bearer”

string

expires_in

required

Token lifetime in seconds (300 standard, 30 execution-scoped)

integer

scope

string

Example

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "read:data"
}

400

Invalid request or unsupported grant type

Media type application/json

object

error

required

Error code (RFC 8693 compatible)

string

Allowed values: invalid_request unsupported_grant_type access_denied server_error not_implemented not_found method_not_allowed

error_description

Human-readable error detail

string

Examples

{
  "error": "unsupported_grant_type",
  "error_description": "grant_type must be urn:ietf:params:oauth:grant-type:token-exchange"
}

{
  "error": "invalid_request",
  "error_description": "unsupported subject_token_type"
}

403

Policy denied the exchange

Media type application/json

object

error

required

Error code (RFC 8693 compatible)

string

Allowed values: invalid_request unsupported_grant_type access_denied server_error not_implemented not_found method_not_allowed

error_description

Human-readable error detail

string

Example

{
  "error": "access_denied",
  "error_description": "policy denied: insufficient blast radius"
}

500

Internal server error

Media type application/json

object

error

required

Error code (RFC 8693 compatible)

string

Allowed values: invalid_request unsupported_grant_type access_denied server_error not_implemented not_found method_not_allowed

error_description

Human-readable error detail

string

Example

{
  "error": "invalid_request"
}