Documentation — Spybara

guides/workload-identity-federation.md +30 −11

Details

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

5Workload identity federation lets trusted workloads exchange externally issued identity tokens for short-lived OpenAI access tokens. Use these guides to configure your external identity provider, create OpenAI service account mappings, and authenticate workloads without storing long-lived API keys.5Workload identity federation lets trusted workloads exchange an externally issued identity token for a short-lived OpenAI access token. X.509 workload identity federation is also available in beta, allowing workloads to exchange a verified certificate identity. Use these guides to configure your external identity provider, create OpenAI service account mappings, and authenticate workloads without storing long-lived API keys.

6 6

7For token exchange request and response details, authorization behavior, and current limitations, see the [workload identity token exchange reference](https://developers.openai.com/api/reference/workload-identity-federation).7For token exchange request and response details, authorization behavior, and current limitations, see the [workload identity token exchange reference](https://developers.openai.com/api/reference/workload-identity-federation).

8 8

10 10

11Workload identity federation has four parts:11Workload identity federation has four parts:

12 12

~~131. A **workload identity provider** describes the trusted issuer. It stores the expected OIDC issuer, audience, and key source used to verify external subject tokens.~~131. A **workload identity provider** describes the external identity. An OIDC provider stores the issuer, audience, and key source used to verify external subject tokens. An X.509 provider derives identity attributes from a client certificate verified against existing Mutual TLS roots.

~~142. A **service account mapping** authorizes specific external token attributes to mint tokens for a particular OpenAI service account within a project.~~142. A **service account mapping** authorizes specific external identity attributes to mint tokens for a particular OpenAI service account within a project.

~~153. A **token exchange** request sends the external subject token to OpenAI and returns a short-lived OpenAI access token.~~153. A **token exchange** request sends an external subject token or presents a client certificate to OpenAI and returns a short-lived OpenAI access token.

~~164. The workload uses the OpenAI-issued access token as a bearer credential to authenticate requests to the OpenAI API.~~164. The workload uses the OpenAI-issued access token as a bearer credential to authenticate requests to the OpenAI API. For X.509 federation, the API request also presents an accepted client certificate.

17 17

18You must be an organization owner to configure this feature. To access it, go to [Organization Settings > Security > Workload Identity Provider](https://platform.openai.com/settings/organization/security/workload-identity-provider). Configure service account mappings from the workload identity provider details page.18You must be an organization owner to configure this feature. Go to [Organization Settings > Security > Workload Identity Provider](https://platform.openai.com/settings/organization/security/workload-identity-provider), then configure service account mappings from the workload identity provider details page. The X.509 provider option is available in beta. If it doesn't appear, contact your system administrator; your administrator can work with OpenAI to enable the beta for your organization.

19 19

20## Choose a setup guide20## Choose a setup guide

21 21

~~22Start with the guide that matches where your workload runs:~~22Start with the guide that matches your workload environment or identity source:

23 23

24 24

25 25

~~26 - **[Kubernetes](https://developers.openai.com/api/docs/guides/workload-identity-federation/kubernetes)**: Use projected service account tokens in self-managed clusters.~~26 - **[X.509 certificates (beta)](https://developers.openai.com/api/docs/guides/workload-identity-federation/x509)**: Configure certificate-backed exchange with the X.509 beta.

27- **[Kubernetes](https://developers.openai.com/api/docs/guides/workload-identity-federation/kubernetes)**: Use projected service account tokens in self-managed clusters.

27- **[AWS](https://developers.openai.com/api/docs/guides/workload-identity-federation/aws)**: Use outbound identity federation or Amazon EKS projected tokens.28- **[AWS](https://developers.openai.com/api/docs/guides/workload-identity-federation/aws)**: Use outbound identity federation or Amazon EKS projected tokens.

28- **[Microsoft Azure](https://developers.openai.com/api/docs/guides/workload-identity-federation/microsoft-azure)**: Use managed identity tokens or AKS projected service account tokens.29- **[Microsoft Azure](https://developers.openai.com/api/docs/guides/workload-identity-federation/microsoft-azure)**: Use managed identity tokens or AKS projected service account tokens.

29- **[Google Cloud](https://developers.openai.com/api/docs/guides/workload-identity-federation/google-cloud)**: Use metadata server identity tokens or GKE projected service account tokens.30- **[Google Cloud](https://developers.openai.com/api/docs/guides/workload-identity-federation/google-cloud)**: Use metadata server identity tokens or GKE projected service account tokens.

35 36

36OpenAI supports OIDC-compatible JWT subject tokens in the documented configurations, including SPIFFE JWT-SVIDs. If you need an OIDC provider that isn't listed, contact us.37OpenAI supports OIDC-compatible JWT subject tokens in the documented configurations, including SPIFFE JWT-SVIDs. If you need an OIDC provider that isn't listed, contact us.

37 38

~~38Each provider guide shows how to issue and inspect a subject token on that platform, and how to configure the OpenAI SDK to exchange it for a short-lived OpenAI access token.~~39Each OIDC provider guide shows how to issue and inspect a subject token on that platform, and how to configure the OpenAI SDK to exchange it for a short-lived OpenAI access token.

39 40

~~40## Configure a Workload Identity Provider~~41## X.509 providers (beta)

43X.509 workload identity federation is available in beta. If X.509 doesn't

44 appear as a provider type, contact your system administrator. Your

45 administrator can work with OpenAI to enable the beta for your organization.

47An X.509 provider derives workload identity attributes from a client certificate that OpenAI verifies against your organization's existing Mutual TLS configuration. It doesn't store certificates or maintain a separate trust store.

49Before creating the provider, configure and activate the trusted CA certificate that anchors your client certificate in [Organization Settings > Security > Mutual TLS](https://platform.openai.com/settings/organization/security/mtls). The [OpenAI Mutual TLS Beta Program](https://help.openai.com/en/articles/10876024-openai-mutual-tls-beta-program) explains certificate requirements, activation scope, supported API endpoints, certificate-chain behavior, and client configuration restrictions.

51Next, create the X.509 provider, derive one non-empty `openai.subject` value, and map that identity to a project service account with only the permissions the workload needs. The workload presents its certificate to the X.509 token endpoint to obtain a short-lived bearer token, then sends the bearer token and an accepted client certificate to the API mTLS endpoint.

53Follow the [X.509 certificate setup guide](https://developers.openai.com/api/docs/guides/workload-identity-federation/x509) for the complete dashboard and request flow.

55## Configure an OIDC Workload Identity Provider

41 56

42Create a Workload Identity Provider for each external issuer you trust. Workload identity federation supports OIDC JWT subject tokens.57Create a Workload Identity Provider for each external issuer you trust. Workload identity federation supports OIDC JWT subject tokens.

43 58

59For certificate-backed workloads, follow the [X.509 certificate guide](https://developers.openai.com/api/docs/guides/workload-identity-federation/x509). X.509 providers reuse active Mutual TLS roots and don't use OIDC issuer, audience, discovery, or JWKS settings.

44Workload Identity Provider configuration includes these dashboard options:61Workload Identity Provider configuration includes these dashboard options:

45 62

46| Option | Description |63| Option | Description |

117 134

118A service account mapping defines which external identities can mint access tokens for an OpenAI service account.135A service account mapping defines which external identities can mint access tokens for an OpenAI service account.

119 136

137For X.509 providers, mapping keys use derived `openai.*` attributes. Prefer an exact `openai.subject` mapping. Raw JWT claims such as `sub`, `aud`, and `iss` apply only to OIDC providers.

138

120Mapping configuration includes these dashboard options:139Mapping configuration includes these dashboard options:

121 140

122| Option | Description |141| Option | Description |

146 165

147### Mapping resolution example166### Mapping resolution example

148 167

149Mapping resolution starts after OpenAI verifies the external subject token. OpenAI looks up mappings for the requested `identity_provider_id` and `service_account_id`, skips disabled mappings, evaluates only the attributes needed by each mapping, and issues a token only if exactly one enabled mapping matches all configured attributes.168Mapping resolution starts after OpenAI verifies the external identity. OpenAI looks up mappings for the requested `identity_provider_id` and `service_account_id`, skips disabled mappings, evaluates only the attributes needed by each mapping, and issues a token only if exactly one enabled mapping matches all configured attributes.

150 169

151For example, a GitHub Actions token might contain these claims:170For example, a GitHub Actions token might contain these claims:

152 171

guides/workload-identity-federation/x509.md +185 −0 created

Details

1# Configure workload identity federation with X.509 certificates (beta)

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.

5X.509 workload identity federation lets a workload exchange an identity from a TLS client certificate for a short-lived OpenAI access token. The workload then calls the OpenAI API with both the access token and an accepted client certificate. This flow replaces the API key, not the client certificate.

7X.509 workload identity federation is available in beta. If X.509 doesn't

8 appear as a provider type, contact your system administrator. Your

9 administrator can work with OpenAI to enable the beta for your organization.

11For token exchange request and response details, see the [workload identity token exchange reference](https://developers.openai.com/api/reference/workload-identity-federation#exchange-an-x509-certificate). For Mutual TLS certificate requirements and supported API endpoints, see the [OpenAI Mutual TLS Beta Program](https://help.openai.com/en/articles/10876024-openai-mutual-tls-beta-program).

13## How it works

15An X.509 workload identity exchange has five parts:

171. Your organization uploads and activates a trusted root certificate in its existing Mutual TLS settings.

182. An X.509 Workload Identity Provider derives `openai.*` attributes from the verified client certificate. It must derive one non-empty `openai.subject` value.

193. A service account mapping authorizes the derived identity to use one OpenAI service account within a project.

204. The workload presents its certificate to the X.509 token endpoint on `mtls.auth.openai.com` and requests a short-lived bearer token. The certificate comes from the TLS connection; the request body doesn't contain a `subject_token`.

215. The workload presents the bearer token and a client certificate to an API route on `mtls.api.openai.com` for API authorization.

23The bearer token and the certificate are authorized independently on the API request. A certificate by itself doesn't authorize an OpenAI API call.

25## Before you begin

27You need:

29- Access to the X.509 workload identity federation beta for your organization.

30- Permission to manage Mutual TLS certificates and Workload Identity Providers for your organization.

31- A project and service account for the workload.

32- A client certificate, its private key, and any intermediate certificates required to build a path to your trusted root.

33- An active trusted root certificate at the organization or project level.

35Keep private keys outside source control and restrict access to the workload that uses them. Don't log private keys, certificate contents, or returned access tokens.

37## Configure Mutual TLS certificate trust

39X.509 Workload Identity Providers reuse your organization's existing Mutual TLS certificate configuration. They don't upload certificates or maintain a separate certificate trust store.

41Follow the [OpenAI Mutual TLS Beta Program](https://help.openai.com/en/articles/10876024-openai-mutual-tls-beta-program) to review CA certificate requirements, supported endpoints, certificate activation behavior, and client configuration. Then open [Organization settings > Security > Mutual TLS](https://platform.openai.com/settings/organization/security/mtls), upload the trusted CA certificate in PEM format, and activate it for the organization or for each project that will use X.509 workload identity federation.

43If your client certificate chains through an intermediate certificate, configure the stable trust anchor and present the leaf followed by the current intermediate certificates during the TLS handshake. OpenAI uses intermediates provided by the request and doesn't retrieve missing intermediates from certificate URLs. The Mutual TLS beta article documents the current chain-support and endpoint restrictions.

45## Configure an X.509 provider

47After X.509 workload identity federation is enabled for your organization:

491. Open [Organization settings > Security > Workload Identity Provider](https://platform.openai.com/settings/organization/security/workload-identity-provider), then select **Create identity provider**.

502. Choose **X.509** for **Provider type**, then enter a name and optional description. X.509 providers don't use OIDC issuer, audience, discovery, or JWKS settings. You can't change the provider type after you create it.

513. Under **Advanced**, optionally add an **Attribute conditions** CEL expression to reject certificates before mapping resolution.

524. Under **Attribute transformations**, enter a non-empty expression for the required `openai.subject` transformation. The dashboard adds the `subject` row when you select X.509 and displays and applies the `openai.` prefix. Choose a stable certificate fact that identifies the workload.

535. Optionally add transformations with other unique `openai.*` names, then select **Create**.

55For example, this configuration uses the certificate common name as the canonical subject and exposes the organizational unit as an additional mapping attribute:

57```json

58[

59 {

60 "attribute": "openai.subject",

61 "expression": "assertion.subject.common_name"

62 },

63 {

64 "attribute": "openai.environment",

65 "expression": "assertion.subject.organizational_unit"

66 }

67]

68```

70Certificate facts are available under `assertion.subject` and `assertion.subject_alt_names`. Transformation results used for mappings must be scalar values. Additional transformations must have unique `openai.*` names.

72For example, an **Attribute conditions** expression can restrict the provider to production certificates:

74```text

75assertion.subject.organizational_unit == "Production"

76```

78## Create a service account mapping

801. From the X.509 provider details page, select **Create mapping**.

812. Select the target project and service account, and grant only the API permissions the workload needs.

823. In the **Key** and **Value** fields, require an exact `openai.subject` value. X.509 mappings support either no assertions, represented as an empty object (`{}`), or assertions whose keys start with `openai.`. During the beta, don't leave the assertions empty.

834. Select **Create**.

85For example:

87| Key | Value |

88| ---------------- | ----------------------- |

89| `openai.subject` | `payments-service-prod` |

91X.509 mappings use derived `openai.*` attributes. They don't match raw JWT claims such as `sub`, `iss`, or `aud`.

93The provider list displays the provider ID, and the mapping details display the selected service account and its service account ID. Record both identifiers; the workload sends them during token exchange.

95## Exchange the certificate for an access token

97Set environment variables for the certificate chain, private key, provider, and service account:

99```bash

100export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"

101export OPENAI_MTLS_KEY="/path/to/client-key.pem"

102export OPENAI_IDENTITY_PROVIDER_ID="idp_example"

103export OPENAI_SERVICE_ACCOUNT_ID="svc_acct_example"

104```

105

106The certificate-chain file should contain the leaf certificate first, followed by any intermediate certificates. Don't include certificate material or a `subject_token` in the request body.

107

108```bash

109curl --cert "$OPENAI_MTLS_CERT_CHAIN" \

110 --key "$OPENAI_MTLS_KEY" \

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

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

113 --data @- <<JSON

114{

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

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

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

118 "service_account_id": "${OPENAI_SERVICE_ACCOUNT_ID}"

119}

120JSON

121```

122

123A successful exchange returns an ordinary short-lived bearer token:

124

125```json

126{

127 "access_token": "eyJ...",

128 "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",

129 "token_type": "Bearer",

130 "expires_in": 3600,

131 "scope": "api.model.read api.model.request"

132}

133```

134

135The `scope` property is returned only when the matching service account mapping has permissions.

136

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

138

139Read the `access_token` value from the successful response into your application's credential store or an environment variable such as `OPENAI_WIF_ACCESS_TOKEN`. Treat it as a secret and don't print, log, or commit it.

140

141## Call the OpenAI API

142

143Set `OPENAI_MODEL` to `gpt-5.6`, the current default, or another model available to the target project. Then send the bearer token and an accepted client certificate to the API mTLS endpoint:

144

145```bash

146curl --request POST \

147 --cert "$OPENAI_MTLS_CERT_CHAIN" \

148 --key "$OPENAI_MTLS_KEY" \

149 --header "Authorization: Bearer $OPENAI_WIF_ACCESS_TOKEN" \

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

151 --data "{\"model\":\"$OPENAI_MODEL\",\"input\":\"Say hello in one sentence.\"}" \

152 "https://mtls.api.openai.com/v1/responses"

153```

154

155Use the bearer token instead of an API key, and continue to present an accepted client certificate on the API request.

156

157The bearer isn't cryptographically bound to the certificate. Reusing the exchange certificate for the API request is the most direct configuration, but the API request can use another certificate that independently satisfies the same current API mTLS policy.

158

159## Token lifetime and renewal

160

161An X.509 workload identity token expires after at most one hour and never outlives the verified client certificate. The exchange doesn't return a refresh token. Repeat the certificate exchange to obtain another access token.

162

163Rotating an intermediate certificate doesn't require changing the configured root. Present the new complete chain on subsequent exchanges and API requests.

164

165## Troubleshoot token exchange

166

167X.509 token exchange returns generic OAuth errors and doesn't expose certificate, root, provider, or mapping details.

168

169| Result | Typical causes |

170| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

171| HTTP `403` | The request used a method or path other than exact `POST /oauth/token` on `mtls.auth.openai.com`. |

172| `invalid_subject_token` | The TLS client certificate is missing or invalid, the presented chain can't reach an active root, the certificate is outside its validity period, or a Mutual TLS certificate-admission rule rejects it. |

173| `invalid_grant` | The X.509 flow isn't enabled, the provider or mapping is invalid or disabled, a provider **Attribute conditions** expression rejects the identity, no applicable roots are active, or no mapping matches. |

174| Server error | OpenAI returned a temporary server error. Retry according to your normal transient-error policy. |

175

176An X.509 exchange never falls back to an OIDC or ordinary OAuth flow.

177

178## Limitations

179

180- X.509 Workload Identity Providers don't maintain a separate certificate trust store.

181- The bearer token isn't certificate-bound and doesn't use DPoP or a `cnf` claim.

182- The certificate exchange isn't certificate-only API authorization. API requests still require the bearer token and an accepted client certificate.

183- OpenAI doesn't fetch missing intermediate certificates from AIA URLs. Present the complete chain during TLS negotiation.

184- OpenAI doesn't perform certificate revocation list (CRL) or OCSP checks during this flow. Plan certificate incident response around Mutual TLS root, provider, and mapping controls and the short lifetime of issued tokens.

185- This flow doesn't add support for SPIFFE X.509-SVIDs. The [SPIFFE guide](https://developers.openai.com/api/docs/guides/workload-identity-federation/spiffe) continues to use JWT-SVIDs.

Documentation 2026-08-06 21:58 UTC to 2026-08-07 00:58 UTC