1# Workload identity token exchange
2
3Use this reference to exchange an externally issued identity token for a short-lived OpenAI access token after you configure a trusted provider and service account mapping. For concepts, dashboard configuration, provider-specific setup, and SDK examples, see the [workload identity federation guide](https://developers.openai.com/api/docs/guides/workload-identity-federation).
4
5## Exchange a subject token
6
7Exchange the external subject token at the OpenAI token endpoint:
8
9```bash
10curl https://auth.openai.com/oauth/token \
11 -H "Content-Type: application/json" \
12 -d '{
13 "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
14 "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
15 "subject_token": "'"$EXTERNAL_OIDC_JWT"'",
16 "identity_provider_id": "'"$IDENTITY_PROVIDER_ID"'",
17 "service_account_id": "'"$SERVICE_ACCOUNT_ID"'"
18 }'
19```
20
21### Request parameters
22
23| Parameter | Required | Description |
24| ---------------------- | -------- | ------------------------------------------------------------------------------------------------ |
25| `grant_type` | Yes | Must be `urn:ietf:params:oauth:grant-type:token-exchange`. |
26| `subject_token_type` | Yes | Supports `urn:ietf:params:oauth:token-type:jwt` and `urn:ietf:params:oauth:token-type:id_token`. |
27| `subject_token` | Yes | The externally issued OIDC JWT from your Workload Identity Provider. |
28| `identity_provider_id` | Yes | The OpenAI Workload Identity Provider ID configured for the external issuer. |
29| `service_account_id` | Yes | The OpenAI service account ID to resolve against the matching service account mapping. |
30
31The token exchange uses the permissions configured on the matching service account mapping. A `scope` value in the request body doesn't grant access.
32
33## Subject token validation
34
35OpenAI verifies the external subject token before resolving a mapping. The token must:
36
37- Be a JWT with a `kid` and supported `alg` in the header.
38- Include `iss`, `aud`, `sub`, `exp`, and `iat` claims.
39- Match the configured Workload Identity Provider issuer and audience.
40- Be signed by a key from the configured JWKS source.
41
42If verification fails, the token exchange returns an authentication error and doesn't mint an OpenAI access token.
43
44After subject token validation succeeds, OpenAI resolves the requested service account mapping against the token's raw claims and derived attributes. Mapping mismatches fail the token exchange during mapping resolution.
45
46## Response
47
48Successful responses include a short-lived bearer token:
49
50```json
51{
52 "access_token": "eyJ...",
53 "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
54 "token_type": "Bearer",
55 "expires_in": 3600,
56 "scope": "api.model.read api.model.request"
57}
58```
59
60The `scope` property is returned only when the resolved mapping has permissions. Access tokens expire after at most one hour and never outlive the external subject token used for the exchange.
61
62## Token exchange errors
63
64If token exchange fails, OpenAI doesn't mint an access token. Common causes include:
65
66| Error category | Typical causes |
67| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
68| Missing request parameter | `subject_token`, `subject_token_type`, `identity_provider_id`, or `service_account_id` is missing. |
69| Unsupported token request | `subject_token_type` isn't `urn:ietf:params:oauth:token-type:jwt` or `urn:ietf:params:oauth:token-type:id_token`. |
70| Provider resolution error | The Workload Identity Provider ID is malformed or unknown. |
71| Subject token verification | The JWT is malformed, the header is missing `kid` or `alg`, the algorithm is unsupported, the signature is invalid, the issuer or audience doesn't match, a required claim is missing, the token is expired, or no JWKS key matches the token `kid`. |
72| Mapping resolution | No mapping exists for the requested service account, the matching mapping is disabled, the token attributes don't match the mapping, or an attribute transformation fails. |
73
74Most subject-token problems are visible by decoding the JWT payload locally and comparing its `iss`, `aud`, `sub`, `exp`, `iat`, and provider-specific claims with your Workload Identity Provider and service account mapping configuration.
75
76If token exchange succeeds but a later OpenAI API request fails, debug the minted access token as an authorization issue. The token still has the project, service account, endpoint authorization, IP allowlist, and other policy checks that apply to normal OpenAI API requests.
77
78## Authorization behavior
79
80Workload identity access tokens are backed by an OpenAI service account and project. On OpenAI API surfaces, they authorize like service-account API credentials rather than user OAuth tokens.
81
82If a mapping defines permissions, those permissions further narrow the effective API access for tokens minted from that mapping. If a mapping doesn't define permissions, OpenAI doesn't add a workload identity federation-specific scope restriction, and authorization is derived from the mapped service account's project and organization roles.
83
84Workload identity tokens don't bypass normal endpoint authorization. The target endpoint must still allow the effective permissions and project access carried by the token.
85
86## Limitations
87
88Workload identity federation currently has the following limitations:
89
90- Workload identity access tokens can't be used to call Admin API endpoints. For Admin APIs, use an admin API key.
91- Each organization can create at most 50 Workload Identity Providers. Each Workload Identity Provider can have at most 50 service account mappings.
92- Workload identity access tokens aren't accepted by these endpoints: `DELETE /v1/models/{id}` and `POST /v1/images/request_audit`.
93- Arbitrary OIDC issuer endpoints other than the providers documented in the [setup guides](https://developers.openai.com/api/docs/guides/workload-identity-federation) aren't supported yet.
