Repository Public
1# Mutual TLS23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45Mutual TLS (mTLS) adds TLS client certificate verification to OpenAI API6requests. After you activate a trusted certificate for an organization or7project, requests in that scope must present an accepted client certificate in8addition to their normal bearer credential.910Use mTLS when a workload can securely hold a client private key and you want11OpenAI to verify its certificate identity before authorizing an API request.12mTLS does not replace API keys, service-account credentials, or workload13identity access tokens.1415X.509 workload identity federation uses the same active mTLS trust anchors.16 The certificate exchange returns a short-lived bearer token, and later API17 calls still send that bearer token plus an accepted API mTLS certificate. See18 [Configure workload identity federation with X.50919 certificates](https://developers.openai.com/api/docs/guides/workload-identity-federation/x509).2021## Before you configure mTLS2223Any API organization can manage mTLS through normal role-based access control24(RBAC):2526- `api.mtls.read` lets a principal list, view, and test certificate settings.27- `api.mtls.write` lets a principal upload, update, activate, deactivate, and28 delete certificates.2930The organization owner role includes these permissions, but you can grant them31through a custom role. For more information, see [Manage permissions in the32OpenAI platform](https://developers.openai.com/api/docs/guides/rbac).3334Prepare:3536- A client certificate and its private key for each workload.37- Any intermediate certificates needed to build a path from the client38 certificate to your trust anchor.39- A stable PEM-encoded trust anchor that you can activate at the organization40 or project level.41- A non-critical project and a tested recovery path before you enable mTLS for42 production traffic.4344Keep private keys outside source control. Do not log private keys, certificate45contents, or bearer credentials.4647## Upload and activate trust4849Upload stores a certificate but does not enforce mTLS. Activation is the step50that changes request behavior.51521. Open [Organization settings > Security > Mutual53 TLS](https://platform.openai.com/settings/organization/security/mtls).542. Upload one PEM-encoded trust anchor for each certificate object. Give it a55 name that identifies the authority and rotation generation.563. Optionally, add a [CEL filter](#filter-client-certificates-with-cel) that57 constrains which verified client certificates that anchor can accept.584. Activate the certificate for a non-critical project first. Send59 representative requests through an [mTLS API host](#use-an-mtls-host) from60 every expected workload.615. Activate the certificate for other projects or for the organization62 after validation succeeds.6364You can also manage certificates through the API:6566| Task | Endpoint |67| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |68| Upload a certificate | `POST /v1/organization/certificates` |69| List organization certificates | `GET /v1/organization/certificates` |70| Retrieve, update, or delete a certificate | `GET`, `POST`, or `DELETE /v1/organization/certificates/{certificate_id}` |71| Activate or deactivate for an organization | `POST /v1/organization/certificates/activate` or `POST /v1/organization/certificates/deactivate` |72| List, activate, or deactivate for a project | `GET /v1/organization/projects/{project_id}/certificates`, `POST /v1/organization/projects/{project_id}/certificates/activate`, or `POST /v1/organization/projects/{project_id}/certificates/deactivate` |7374Use a credential with the required `api.mtls.read` or `api.mtls.write`75permission. For request and response schemas, see the [organization76certificates API reference](https://developers.openai.com/api/reference/resources/admin/subresources/organization).7778## Certificate requirements7980Use one PEM-encoded trust anchor per certificate object. The upload must81contain a valid certificate that expires more than one day after upload. The82client certificate must include an Authority Key Identifier (AKI) for request83verification.8485For a request to pass mTLS:8687- The client certificate must be valid at request time and suitable for TLS88 client authentication.89- The client certificate must build a valid path to an active organization- or90 project-level trust anchor.91- If the path includes intermediate certificates, the client must present them92 during the TLS handshake.93- The configured trust anchor and the client chain must pass standard X.50994 client-certificate path validation.9596If an upload contains more than one PEM-encoded certificate, request-chain97verification uses only the first configured certificate as the anchor; do not98rely on PEM-bundle semantics.99100OpenAI does not fetch missing intermediates from Authority Information Access101(AIA) URLs and does not perform certificate revocation list (CRL) or Online102Certificate Status Protocol (OCSP) checks. Present the complete required chain103and manage incident response through certificate rotation, deactivation, and104your own certificate lifecycle controls.105106## Understand verification order107108OpenAI checks active project-level certificates before active109organization-level certificates. If neither scope has an active certificate,110mTLS does not add a certificate check to the request.111112When an active certificate exists, OpenAI verifies client identity in this113order:1141151. OpenAI first attempts the existing direct path, which verifies the client116 certificate directly against an active anchor without request117 intermediates.1182. After an ordinary direct-path no-match, OpenAI tries request-chain119 verification with the client certificate and the intermediate certificates120 presented by the TLS connection.1213. If a path verifies, OpenAI evaluates the active certificate's CEL filter, if122 present, against the verified client certificate.123124Request-chain verification is available by default.125126The request-chain path is a fallback after an ordinary no-match, not a recovery127path for every direct-path error. Missing or malformed certificate material, a128missing AKI, or a deterministic error after the direct path selects an129anchor can fail the request without trying the presented chain.130131## Filter client certificates with CEL132133Attach an optional Common Expression Language (CEL) filter to an uploaded134certificate to constrain the verified client certificates that anchor accepts.135The expression must evaluate to a boolean and runs against the verified client136certificate on both the direct and request-chain paths.137138CEL exposes these fields:139140- `subject.common_name`, `subject.country_code`, `subject.organization`,141 `subject.organizational_unit`, `subject.locality`, `subject.province`,142 `subject.street_address`, and `subject.postal_code`.143- `subject_alt_names`, a list whose entries expose `type`, `value`, and `oid`.144 Supported SAN type identifiers are `DNS`, `EMAIL`, `IP_ADDRESS`, `URI`, and145 `CUSTOM`.146147For example, require a production organizational unit and a DNS SAN in a148specific namespace:149150```text151subject.organizational_unit == "Production" &&152subject_alt_names.exists(san, san.type == DNS && san.value.endsWith(".example.com"))153```154155A certificate that verifies but does not match the filter fails with156`certificate_attribute_verification_failed`. OpenAI rejects a policy that does not pass validation when you save it.157158## Use an mTLS host159160Send API traffic to an mTLS host instead of `api.openai.com`:161162| Host | Use |163| ------------------------ | ------------------------------------- |164| `mtls.api.openai.com` | Default API mTLS host. |165| `mtls-us.api.openai.com` | United States regional API mTLS host. |166| `mtls-eu.api.openai.com` | EU regional API mTLS host. |167168mTLS is host-based. Use the same `/v1` route you would call on the169corresponding API surface, and test each API and model that your workload170uses. Route and model availability can differ across regional hosts.171172For example, send a normal bearer credential and a client certificate to the173default mTLS host:174175```bash176export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"177export OPENAI_MTLS_KEY="/path/to/client-key.pem"178179curl https://mtls.api.openai.com/v1/models \180 --cert "$OPENAI_MTLS_CERT_CHAIN" \181 --key "$OPENAI_MTLS_KEY" \182 --header "Authorization: Bearer $OPENAI_API_KEY"183```184185The certificate-chain file should contain the client certificate first,186followed by any required intermediates. Do not send certificate material in187HTTP headers or request bodies.188189X.509 workload identity federation uses a separate exact exchange endpoint:190`POST https://mtls.auth.openai.com/oauth/token`. That exchange produces a191short-lived bearer token; it does not provide certificate-only API authentication. For192the complete request shape, see the [workload identity token exchange193reference](https://developers.openai.com/api/reference/workload-identity-federation#exchange-an-x509-certificate).194195## Rotate certificates196197Rotate trust anchors with overlap so existing workloads keep working:1981991. Upload the new trust anchor without deactivating the old one.2002. Activate the new anchor in each intended project or at the organization201 level.2023. Update workloads to present client certificates that chain to the new203 anchor, then test each mTLS host and API surface they use.2044. Deactivate the old anchor after all workloads have moved.2055. Delete the old certificate only after you deactivate it for the organization206 and every project.207208You can rotate intermediates without changing the configured trust anchor.209Present the new complete chain on later requests.210211## Troubleshoot requests212213Use stable error codes to distinguish configuration errors from temporary214service errors:215216| Error code | What to check |217| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |218| `certificate_required` | An active certificate applies, but the request did not present required client certificate material. |219| `invalid_certificate` | OpenAI cannot decode or parse the client certificate, or the certificate lacks the AKI required for verification. |220| `certificate_verification_failed` | The client certificate or presented chain does not reach an active trust anchor. |221| `certificate_attribute_verification_failed` | The certificate path verified, but the CEL filter rejected the verified client certificate. |222| `authentication_temporarily_unavailable` | A verifier timeout, internal dependency error, or CEL evaluator error caused HTTP `503`. Retry with your normal transient-error policy. |223224For management requests, `mtls_certificate_invalid` means the uploaded PEM225did not pass validation, `expired_certificate` means it expires too soon or has226expired, `mtls_cel_policy_invalid` means the filter does not pass validation, and227`certificate_in_use` means you must deactivate the certificate before deleting228it.229230## Current limitations231232- An organization can upload up to 50 certificate objects.233- mTLS adds certificate verification to normal API authentication; it does not provide234 certificate-only API authorization.235- OpenAI does not fetch AIA intermediates and does not perform CRL or OCSP236 checks.237- Private Link is not compatible with mTLS. See [Private238 Link](https://developers.openai.com/api/docs/guides/private-link) when you need a private Azure network239 path instead.240- The supported API mTLS hosts are `mtls.api.openai.com`,241 `mtls-us.api.openai.com`, and `mtls-eu.api.openai.com`. Do not assume every242 other regional API host has an mTLS counterpart.243- X.509 workload identity federation does not return a refresh token and does244 not use DPoP, a `cnf` claim, or a certificate-bound bearer token. See245 [Configure workload identity federation with X.509246 certificates](https://developers.openai.com/api/docs/guides/workload-identity-federation/x509).