Reference 2026-08-06 18:59 UTC to 2026-08-07 00:58 UTC

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 token7## 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 validation35## Exchange an X.509 certificate

36 

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.

38 

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

40 

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

42 

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```

57 

58### X.509 request parameters

59 

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

67 

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

69 

70## Identity validation

71 

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

86 

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.

88 

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.

90 

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.

92 

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.