Exchange an existing workload identity
Optional authenticated execution-host interface for integrations that already have an admitted workload identity. This is not public signup or dashboard login. Use the endpoint and registration supplied by your host owner; no managed token endpoint is issued. Send application/json; maximum body 32 KiB. Tokens expire and are sender-bound; refresh outside tool execution.
Request fields
Unknown fields are rejected. JWT exchange uses a trusted workload assertion. Delegation uses an existing access token and cannot expand its authority.
| Field | Type | Meaning |
|---|---|---|
| grant_type | string; required | urn:ietf:params:oauth:grant-type:token-exchange |
| subject_token_type | string; required | urn:ietf:params:oauth:token-type:jwt or urn:ietf:params:oauth:token-type:access_token |
| subject_token | string; required | Workload assertion or parent access token. Never log it. |
| registration | string; JWT exchange | Existing admitted workload registration. Does not create one. |
| connection | string; delegation | Connection within the parent authority. |
| subject | string; optional delegation | Delegated subject; defaults to delegate. |
| audience | string; required | Intended execution audience; must match admitted authority. |
| tools | string[]; required | Requested admitted tool names; delegation can only narrow scope. |
| ttl | integer seconds; required | Positive lifetime, at most 900 seconds and no longer than the source credential permits. |
| cnf | object; required | Exactly one sender binding: {"jkt":"<public-key-thumbprint>"} or {"x5t#S256":"<certificate-thumbprint>"}. |
Request example
Illustrative JWT exchange body. Replace the assertion, registration, audience and thumbprint with values admitted by your execution host; never paste real token material into prompts or logs.
{
"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
"subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
"subject_token": "<workload-assertion>",
"registration": "example-registration",
"audience": "example-execution",
"tools": [
"vendor.read"
],
"ttl": 300,
"cnf": {
"jkt": "<public-key-thumbprint>"
}
}Success: HTTP 200
The response is application/json with Cache-Control: no-store and Pragma: no-cache. access_token is sensitive; token_type is DPoP for jkt binding or Bearer for certificate binding. expires_at is Unix seconds. Use the corresponding proof or certificate on execution and recovery requests.
{
"access_token": "<access-token>",
"token_type": "DPoP",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"expires_in": 300,
"expires_at": 1792933500
}Errors and retry behavior
JSON errors use {"error":"code"}. 400 invalid_request or unsupported_grant_type: fix the request. 413: reduce body size. 401 identity_*: assertion, expiry or proof refused; acquire a valid identity rather than retry the same proof. 403 identity_*: scope, tenant or registration refused; ask the host owner to authorize this workload and scope. 429 identity_*: exchange capacity/rate exhausted; back off. 503 identity_unavailable or identity_*: exchange unavailable; refresh credentials outside the call path. Do not fall back to an unrelated credential automatically. Replay and rate state are local to one process, not shared across hosts.