--- title: "Exchange credentials for a TEA access token" method: POST path: "/token" tags: ["TEA Authentication"] --- # Exchange credentials for a TEA access token `POST /token` Exchange credentials for a TEA access token. A TEA server that requires authentication on any of its endpoints shall implement this endpoint, and shall support the `client_credentials` grant type with HTTP Basic client authentication (RFC 6749 section 2.3.1, RFC 7617): the API key identifier is sent as the user-id and the API key secret as the password. A server that requires no authentication need not implement it. Clients do not probe this endpoint to discover whether authentication is required: they issue the resource request, and a `401` response carrying a `WWW-Authenticate: Bearer` challenge is the signal to obtain a token here. A `404` from this endpoint, with or without a TEA error body, means only that it is not implemented. A server that mounts the path without implementing the exchange should answer with the shared object-not-found response and `error: NOT_IMPLEMENTED`. Servers may support additional grant types for federated identity, for example SAML 2.0 assertions (RFC 7522) or JWT assertions (RFC 7523), and may authenticate the client with mutual TLS (RFC 8705) instead of Basic. Whichever grant type is used, the token returned by this endpoint is the only credential accepted on the other TEA endpoints. RFC 8693 token exchange (`urn:ietf:params:oauth:grant-type:token-exchange`) is outside the scope of the TEA 1.0 interoperable authentication profile. TEA 1.0 does not specify the request or response contract for this grant. Implementations may support it as an extension by separate agreement, but clients shall not assume its availability based solely on TEA 1.0 conformance. Such extensions do not remove the requirement for servers requiring authentication to support the `client_credentials` baseline. The access token is opaque to the client: clients shall not inspect, parse, or depend on its contents. The empty security requirement on this operation does not authorize anonymous `client_credentials` issuance. It only allows the alternate client-authentication methods described above (for example, mutual TLS, JWT client assertion (RFC 7523), or credentials in the request body). For the baseline `client_credentials` grant with HTTP Basic, unauthenticated requests shall not be accepted: servers shall respond with `401`, `error: invalid_client`, and a `WWW-Authenticate: Basic` challenge (see `401-token-error`; RFC 6749 section 5.2). ## Response `200` Credentials accepted, access token issued - TokenResponse — Successful token response, as defined in RFC 6749 section 5.1. - `access_token` string, required — The issued access token, presented on other TEA endpoints as `Authorization: Bearer `. Opaque to the client. - `token_type` 'Bearer', required — Token type. Always `Bearer` in TEA. - `expires_in` integer — Lifetime of the access token in seconds. Servers should include this so that clients can re-authenticate before expiry rather than on failure. - `scope` string — Granted scope, when it differs from the scope requested. ## Other responses - `400` — The token request was malformed, used an unsupported grant type, or the credentials presented were not valid for the requested grant. - `401` — Client authentication failed (`error: invalid_client`). Returned instead of 400 when the client attempted to authenticate using the `Authorization` header (RFC 6749 section 5.2). For the baseline Basic exchange this includes a missing or invalid `Authorization: Basic` credential. Servers shall include `WWW-Authenticate: Basic`. - `404` — Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone: - `error: OBJECT_UNKNOWN` — no such object (or its existence is concealed from this client). - `error: NOT_IMPLEMENTED` — optional capability or endpoint not provided (for CLE: lifecycle data; for `/token`: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional. - `error: SIGNATURE_NOT_FOUND` — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer `OBJECT_UNKNOWN` for every sub-resource of it, signatures included. Concealment applies only after authentication. A request to a protected object with no valid access token shall receive `401` (see `401-unauthorized`), not a concealing `404`. Clients shall not infer from `404` alone whether the object is absent, withheld, or lacking an optional capability or sub-resource. ## Changes - **2026-09-20** `f698addb5d2b` — 2 info - added the optional property `message` to the response with the `404` status - removed the `OBJECT_NOT_SHAREABLE` enum value from the `error` response property for the response status `404` - **2026-09-18** `772035fe6917` — 1 info - added the non-success response with the status `404` - **2026-09-16** `2ec82278183e` — 2 warning - removed the request property `subject_token` - removed the request property `subject_token_type` - **2026-09-16** `a539fe01ed1a` — 2 info - added the new optional request property `subject_token` - added the new optional request property `subject_token_type` - **2026-09-12** `d28a7b52c2b1` — 2 warning - removed the request property `subject_token` - removed the request property `subject_token_type` [Full history](https://skmtc.dev/cyclonedx/apis/transparency-exchange-api/changes/token/post.md) --- [API](https://skmtc.dev/cyclonedx/apis/transparency-exchange-api.md) · [All operations](https://skmtc.dev/cyclonedx/apis/transparency-exchange-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cyclonedx/apis/transparency-exchange-api/revisions/4d4c7959bc18?raw)