Workload identity token exchange

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

Use 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. It also describes the beta X.509 certificate exchange. For concepts, dashboard configuration, and setup guides, see the workload identity federation guide.

Exchange a JWT subject token

Exchange the external subject token at the OpenAI token endpoint:

curl https://auth.openai.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "subject_token": "'"$EXTERNAL_OIDC_JWT"'",
    "identity_provider_id": "'"$IDENTITY_PROVIDER_ID"'",
    "service_account_id": "'"$SERVICE_ACCOUNT_ID"'"
  }'

Request parameters

Parameter	Required	Description
`grant_type`	Yes	Must be `urn:ietf:params:oauth:grant-type:token-exchange`.
`subject_token_type`	Yes	Supports `urn:ietf:params:oauth:token-type:jwt` and `urn:ietf:params:oauth:token-type:id_token`.
`subject_token`	Yes	The externally issued OIDC JWT or SPIFFE JWT-SVID from your Workload Identity Provider.
`identity_provider_id`	Yes	The OpenAI Workload Identity Provider ID configured for the external issuer.
`service_account_id`	Yes	The OpenAI service account ID to resolve against the matching service account mapping.

The token exchange uses the permissions configured on the matching service account mapping. A scope value in the request body doesn't grant access.

Exchange an X.509 certificate

X.509 certificate exchange is available in beta. If X.509 doesn't appear as a provider type, contact your system administrator. Your administrator can work with OpenAI to enable the beta for your organization.

Present the client certificate during TLS negotiation with the dedicated X.509 token endpoint. Don't include a subject_token in the request body.

For provider and service account mapping configuration, follow the X.509 certificate setup guide. For certificate requirements, activation, supported endpoints, and client configuration, see the OpenAI Mutual TLS Beta Program.

curl --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --request POST "https://mtls.auth.openai.com/oauth/token" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token_type": "urn:openai:params:oauth:token-type:x509",
  "identity_provider_id": "${OPENAI_IDENTITY_PROVIDER_ID}",
  "service_account_id": "${OPENAI_SERVICE_ACCOUNT_ID}"
}
JSON

X.509 request parameters

Parameter	Required	Description
`grant_type`	Yes	Must be `urn:ietf:params:oauth:grant-type:token-exchange`.
`subject_token_type`	Yes	Must be `urn:openai:params:oauth:token-type:x509`.
`identity_provider_id`	Yes	The OpenAI X.509 Workload Identity Provider ID.
`service_account_id`	Yes	The OpenAI service account ID to resolve against the provider's service account mappings.
`subject_token`	No	Omit this parameter. OpenAI obtains certificate identity only from the authenticated TLS connection.

The X.509 endpoint accepts only exact POST /oauth/token requests on mtls.auth.openai.com. Other methods and paths return HTTP 403.

Identity validation

JWT subject token validation

OpenAI verifies the external subject token before resolving a mapping. The token must:

Be a JWT with a kid and supported alg in the header.
Include iss, aud, sub, exp, and iat claims.
Match the configured Workload Identity Provider issuer and audience.
Be signed by a key from the configured JWKS source.

If verification fails, the token exchange returns an authentication error and doesn't mint an OpenAI access token.

After 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.

X.509 certificate validation

OpenAI verifies the client certificate against active Mutual TLS roots in the resolved organization and project context. The client must present any intermediate certificates required to build the path. OpenAI doesn't fetch missing intermediates from certificate URLs.

During certificate validation, OpenAI applies the certificate-admission rules configured with the active Mutual TLS root. After validation succeeds, OpenAI evaluates the provider's Attribute conditions, derives its openai.* attributes, and resolves exactly one enabled mapping for the requested service account. X.509 providers must derive one non-empty openai.subject value.

Malformed or missing certificate material, an invalid chain, a root mismatch, a certificate outside its validity period, or rejection by a Mutual TLS certificate-admission rule returns invalid_subject_token. Rejection by the provider's Attribute conditions expression returns invalid_grant. Other provider, mapping, rollout, or active-root configuration failures also return invalid_grant. X.509 requests never fall back to OIDC or another OAuth flow.

Response

Successful responses include a short-lived bearer token:

{
  "access_token": "eyJ...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api.model.read api.model.request"
}

The scope property is returned only when the resolved mapping has permissions. Access tokens expire after at most one hour. A JWT exchange token never outlives its external subject token, and an X.509 exchange token never outlives the verified client certificate. Token exchange doesn't return a refresh token.

The expires_in value of 3600 in the example is illustrative. The returned lifetime can be shorter when the verified client certificate expires sooner.

Token exchange errors

If token exchange fails, OpenAI doesn't mint an access token. Common causes include:

Error category	Typical causes
Missing JWT request parameter	`subject_token`, `subject_token_type`, `identity_provider_id`, or `service_account_id` is missing from a JWT exchange.
Unsupported token request	`subject_token_type` isn't a supported JWT type or the X.509 token type, or the request uses fields that aren't accepted for that mode.
Provider resolution error	The Workload Identity Provider ID is malformed, unknown, disabled, or incompatible with the requested exchange mode.
JWT 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`.
X.509 certificate verification	The client certificate is missing or malformed, the presented path doesn't reach an active root, the certificate is outside its validity period, or it doesn't satisfy configured certificate rules.
Mapping resolution	No mapping exists for the requested service account, the matching mapping is disabled, the identity attributes don't match the mapping, or an attribute transformation fails.

Most 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.

If 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. An X.509 workload must also send an accepted client certificate to mtls.api.openai.com on the API request.

Authorization behavior

Workload 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.

If 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.

Workload identity tokens don't bypass normal endpoint authorization. The target endpoint must still allow the effective permissions and project access carried by the token.

For X.509 exchanges, the bearer token replaces the API key, not the client certificate. The bearer and API mTLS certificate are verified independently. The bearer isn't certificate-bound and doesn't use DPoP or a cnf claim.

Limitations

Workload identity federation currently has the following limitations:

Workload identity access tokens can't be used to call Admin API endpoints. For Admin APIs, use an admin API key.
Each organization can create at most 50 Workload Identity Providers. Each Workload Identity Provider can have at most 50 service account mappings.
Workload identity access tokens aren't accepted by these endpoints: DELETE /v1/models/{id} and POST /v1/images/request_audit.
Arbitrary OIDC issuer endpoints other than the providers documented in the setup guides aren't supported yet.
X.509 Workload Identity Providers reuse active Mutual TLS roots and don't have a separate certificate trust store.
X.509 certificate exchange doesn't perform certificate revocation list (CRL) or OCSP checks.
SPIFFE support is limited to JWT-SVID subject tokens. X.509-SVIDs aren't supported by this token exchange endpoint.

workload-identity-federation.md +63 −11

2 2

3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 4

5Use 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).5Use 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. It also describes the beta X.509 certificate exchange. For concepts, dashboard configuration, and setup guides, see the [workload identity federation guide](https://developers.openai.com/api/docs/guides/workload-identity-federation).

6 6

~~7## Exchange a subject token~~7## Exchange a JWT subject token

8 8

9Exchange the external subject token at the OpenAI token endpoint:9Exchange the external subject token at the OpenAI token endpoint:

10 10

32 32

33The token exchange uses the permissions configured on the matching service account mapping. A `scope` value in the request body doesn't grant access.33The token exchange uses the permissions configured on the matching service account mapping. A `scope` value in the request body doesn't grant access.

34 34

~~35## Subject token validation~~35## Exchange an X.509 certificate

37X.509 certificate exchange is available in beta. If X.509 doesn't appear as a provider type, contact your system administrator. Your administrator can work with OpenAI to enable the beta for your organization.

39Present the client certificate during TLS negotiation with the dedicated X.509 token endpoint. Don't include a `subject_token` in the request body.

41For provider and service account mapping configuration, follow the [X.509 certificate setup guide](https://developers.openai.com/api/docs/guides/workload-identity-federation/x509). For certificate requirements, activation, supported endpoints, and client configuration, see the [OpenAI Mutual TLS Beta Program](https://help.openai.com/en/articles/10876024-openai-mutual-tls-beta-program).

43```bash

44curl --cert "$OPENAI_MTLS_CERT_CHAIN" \

45 --key "$OPENAI_MTLS_KEY" \

46 --request POST "https://mtls.auth.openai.com/oauth/token" \

47 --header "Content-Type: application/json" \

48 --data @- <<JSON

49{

50 "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",

51 "subject_token_type": "urn:openai:params:oauth:token-type:x509",

52 "identity_provider_id": "${OPENAI_IDENTITY_PROVIDER_ID}",

53 "service_account_id": "${OPENAI_SERVICE_ACCOUNT_ID}"

54}

55JSON

56```

58### X.509 request parameters

60| Parameter | Required | Description |

61| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------- |

62| `grant_type` | Yes | Must be `urn:ietf:params:oauth:grant-type:token-exchange`. |

63| `subject_token_type` | Yes | Must be `urn:openai:params:oauth:token-type:x509`. |

64| `identity_provider_id` | Yes | The OpenAI X.509 Workload Identity Provider ID. |

65| `service_account_id` | Yes | The OpenAI service account ID to resolve against the provider's service account mappings. |

66| `subject_token` | No | Omit this parameter. OpenAI obtains certificate identity only from the authenticated TLS connection. |

68The X.509 endpoint accepts only exact `POST /oauth/token` requests on `mtls.auth.openai.com`. Other methods and paths return HTTP `403`.

70## Identity validation

72### JWT subject token validation

36 73

37OpenAI verifies the external subject token before resolving a mapping. The token must:74OpenAI verifies the external subject token before resolving a mapping. The token must:

38 75

45 82

46After 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.83After 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.

47 84

85### X.509 certificate validation

87OpenAI verifies the client certificate against active Mutual TLS roots in the resolved organization and project context. The client must present any intermediate certificates required to build the path. OpenAI doesn't fetch missing intermediates from certificate URLs.

89During certificate validation, OpenAI applies the certificate-admission rules configured with the active Mutual TLS root. After validation succeeds, OpenAI evaluates the provider's **Attribute conditions**, derives its `openai.*` attributes, and resolves exactly one enabled mapping for the requested service account. X.509 providers must derive one non-empty `openai.subject` value.

91Malformed or missing certificate material, an invalid chain, a root mismatch, a certificate outside its validity period, or rejection by a Mutual TLS certificate-admission rule returns `invalid_subject_token`. Rejection by the provider's **Attribute conditions** expression returns `invalid_grant`. Other provider, mapping, rollout, or active-root configuration failures also return `invalid_grant`. X.509 requests never fall back to OIDC or another OAuth flow.

48## Response93## Response

49 94

50Successful responses include a short-lived bearer token:95Successful responses include a short-lived bearer token:

59}104}

60```105```

61 106

~~62The `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.~~107The `scope` property is returned only when the resolved mapping has permissions. Access tokens expire after at most one hour. A JWT exchange token never outlives its external subject token, and an X.509 exchange token never outlives the verified client certificate. Token exchange doesn't return a refresh token.

108

109The `expires_in` value of `3600` in the example is illustrative. The returned lifetime can be shorter when the verified client certificate expires sooner.

63 110

64## Token exchange errors111## Token exchange errors

65 112

66If token exchange fails, OpenAI doesn't mint an access token. Common causes include:113If token exchange fails, OpenAI doesn't mint an access token. Common causes include:

67 114

68| Error category | Typical causes |115| Error category | Typical causes |

69| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |116| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

70| Missing request parameter | `subject_token`, `subject_token_type`, `identity_provider_id`, or `service_account_id` is missing. |117| Missing JWT request parameter | `subject_token`, `subject_token_type`, `identity_provider_id`, or `service_account_id` is missing from a JWT exchange. |

71| Unsupported token request | `subject_token_type` isn't `urn:ietf:params:oauth:token-type:jwt` or `urn:ietf:params:oauth:token-type:id_token`. |118| Unsupported token request | `subject_token_type` isn't a supported JWT type or the X.509 token type, or the request uses fields that aren't accepted for that mode. |

72| Provider resolution error | The Workload Identity Provider ID is malformed or unknown. |119| Provider resolution error | The Workload Identity Provider ID is malformed, unknown, disabled, or incompatible with the requested exchange mode. |

73| 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`. |120| JWT 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`. |

74| 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. |121| X.509 certificate verification | The client certificate is missing or malformed, the presented path doesn't reach an active root, the certificate is outside its validity period, or it doesn't satisfy configured certificate rules. |

122| Mapping resolution | No mapping exists for the requested service account, the matching mapping is disabled, the identity attributes don't match the mapping, or an attribute transformation fails. |

75 123

76Most 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.124Most 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.

77 125

78If 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.126If 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. An X.509 workload must also send an accepted client certificate to `mtls.api.openai.com` on the API request.

79 127

80## Authorization behavior128## Authorization behavior

81 129

85 133

86Workload identity tokens don't bypass normal endpoint authorization. The target endpoint must still allow the effective permissions and project access carried by the token.134Workload identity tokens don't bypass normal endpoint authorization. The target endpoint must still allow the effective permissions and project access carried by the token.

87 135

136For X.509 exchanges, the bearer token replaces the API key, not the client certificate. The bearer and API mTLS certificate are verified independently. The bearer isn't certificate-bound and doesn't use DPoP or a `cnf` claim.

137

88## Limitations138## Limitations

89 139

90Workload identity federation currently has the following limitations:140Workload identity federation currently has the following limitations:

93- Each organization can create at most 50 Workload Identity Providers. Each Workload Identity Provider can have at most 50 service account mappings.143- Each organization can create at most 50 Workload Identity Providers. Each Workload Identity Provider can have at most 50 service account mappings.

94- Workload identity access tokens aren't accepted by these endpoints: `DELETE /v1/models/{id}` and `POST /v1/images/request_audit`.144- Workload identity access tokens aren't accepted by these endpoints: `DELETE /v1/models/{id}` and `POST /v1/images/request_audit`.

95- 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.145- 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.

146- X.509 Workload Identity Providers reuse active Mutual TLS roots and don't have a separate certificate trust store.

147- X.509 certificate exchange doesn't perform certificate revocation list (CRL) or OCSP checks.

96- SPIFFE support is limited to JWT-SVID subject tokens. X.509-SVIDs aren't supported by this token exchange endpoint.148- SPIFFE support is limited to JWT-SVID subject tokens. X.509-SVIDs aren't supported by this token exchange endpoint.