Stop storing API keys in CI: use workload identity

A secret is not an identity strategy

On 8 October 2026, Mutual TLS and X.509 Workload Identity Federation became generally available for the OpenAI API. This is more than another sign-in option. It is a useful reason to retire one of the most convenient and risky habits in modern product teams: copying a long-lived API key into CI, a serverless platform and production servers, then treating that key as an identity for years.

An API key mainly answers one question: who possesses this secret? It does not reliably explain which workflow is running, which repository it came from, which environment it belongs to or how long its permission should last. A copy is as powerful as the original. If it leaks, it remains valid until somebody actively rotates it.

Workload identity reverses the model. A machine proves who it is with an identity it already has. OpenAI verifies that evidence, maps it to a service account and issues a short-lived access token. The production process no longer needs a permanently stored OpenAI API key.

Three layers that teams often confuse

Before migrating, separate three different controls:

• Workload Identity Federation exchanges verified external evidence for a short-lived OpenAI access token.
• Mutual TLS requires an accepted client certificate on the TLS connection in addition to a bearer credential.
• Service accounts and their roles determine what the mapped workload may actually do in the selected project.

None automatically replaces the others. With X.509 workload identity, the API key is replaced by a short-lived access token, but the client certificate remains. On the later API call, the bearer token and accepted certificate are authorised independently. A certificate alone does not authorise an API request.

Plain mTLS is not automatically workload identity either. It adds certificate verification to normal authentication. An application may still use mTLS with an API key. Federation delivers the larger change when the long-lived OpenAI key disappears and a bounded machine identity takes its place.

OIDC is usually the first move for CI

GitHub Actions can issue a signed OIDC token for one workflow job. OpenAI validates the issuer, audience, signature and configured mapping attributes before issuing a short-lived access token. The workflow needs id-token: write. That permission allows it to request an identity token; it does not grant write access to repository contents.

A good pipeline flow looks like this:

1. The job starts in a known repository and environment.
2. GitHub issues a short-lived OIDC token for one exact audience.
3. an OpenAI identity-provider rule accepts only the intended claims;
4. the mapping points to a dedicated service account in the correct project;
5. OpenAI issues a short-lived access token;
6. the job uses that token and discards it with the runner.

The provider ID, service-account ID and audience can live in ordinary CI variables; they are not bearer credentials. The mapping rule is the critical boundary. “Every job in this organisation” may be convenient, but it creates another large shared trust zone. Match repository, branch or environment only as broadly as the real process requires.

X.509 fits workloads that already understand certificates

Not every environment produces suitable OIDC tokens. Some organisations already operate a private PKI, hardware-protected keys or certificates for machine identity. X.509 workload identity can be a good fit there.

The flow has five parts:

1. A trusted root CA is uploaded and activated in the Mutual TLS settings.
2. The identity provider derives attributes from the verified client certificate, including one non-empty openai.subject.
3. A mapping connects that identity to exactly one OpenAI service account.
4. The workload presents its certificate at the X.509 token endpoint and receives a short-lived bearer token.
5. For the API call, it sends the bearer token and an accepted client certificate to the mTLS API host.

The token lasts no more than one hour and never outlives the verified client certificate. There is no refresh token; the application performs another exchange before expiry. Official SDKs can handle the certificate, token exchange, mTLS host and renewal.

The honest limitation matters: this model still has a private key. It does not belong in Git, logs or a shared CI secret. It must be protected so only the intended workload can use it. Federation does not remove every secret. It reduces the lifetime, scope and reuse of the actual API access.

One identity per product boundary

A common architecture mistake is one “AI Production” service account shared by the website, support bot, data pipeline and internal tools. The API key may disappear, but the blast radius remains almost unchanged.

Prefer identities that follow real product and environment boundaries:

• production support summaries;
• staging content preparation;
• evaluations in CI;
• internal analysis jobs;
• interactive developer environments.

Each workload gets its own mapping and a service account with the required project roles. A compromised workflow can then be disabled without stopping every other application. Cost, error and audit signals also become easier to understand because one identity has one concrete purpose.

Human usage should not share the same mapping. A developer laptop, a CI job and a production service have different lifecycles, risks and recovery paths. Combining them under one identity removes the separation workload identity is meant to create.

Claims are a firewall, not a name tag

A federation provider proves only that a token came from a trusted issuer. Attribute conditions and mappings decide which of the many identities at that issuer may enter.

For GitHub Actions, review at least:

• the exact audience;
• repository owner and repository;
• branch, tag or protected environment;
• workflow file or job context where it defines the boundary;
• expected issuer and short token lifetime.

For X.509, subject, SANs, issuing chain and any CEL filters belong in the same threat analysis. A broad wildcard saves configuration but turns a targeted entrance into a master key.

The rule should explain which real machine or pipeline is allowed in. A technical condition nobody can connect to the deployment process will eventually be opened too far or broken accidentally.

Rotate without a big bang

Certificate rotation should not require downtime. OpenAI recommends overlap for trust anchors:

1. upload the new root or trust anchor without deactivating the old one;
2. activate it in a non-critical project first;
3. move workloads to certificates that chain to the new anchor and test every host and API surface in use;
4. deactivate the old anchor only after migration is complete;
5. delete it only after deactivation.

Intermediate certificates can rotate without replacing the root. The workload must still present the complete current chain during the TLS handshake; OpenAI does not fetch missing intermediates from certificate URLs.

For OIDC, focus on signing keys, audience and provider configuration. Old and new public keys should both validate during the transition. Token exchange also needs to tolerate clock skew and transient failures without continuing to reuse an expired token.

Rollout needs a way back

Activating mTLS changes request behaviour, so it should not begin across the whole organisation. The official guide recommends a non-critical project and a tested recovery path.

A dependable rollout includes:

• a small smoke test through the same SDK and network path as production;
• tests for every regional mTLS host actually used;
• an alert for failed token exchanges and certificate errors;
• a documented owner for provider, mapping, service account and trust anchor;
• a time-limited fallback that cannot become the permanent solution;
• a rehearsal of deactivation and reactivation.

X.509 exchange errors intentionally do not reveal detailed root, provider or mapping information. Monitoring therefore needs to expose your own steps: certificate expiry, successful exchanges, token expiry, service account and target host — without logging private keys, certificate contents or access tokens.

What this does not solve automatically

Short-lived tokens are not a free pass. The X.509 documentation lists important boundaries:

• The bearer token is not cryptographically bound to one certificate.
• There is no DPoP or cnf claim.
• This flow does not check certificate revocation through CRL or OCSP.
• Missing intermediate certificates are not fetched automatically.
• Codex does not support X.509 federation; use OIDC or SPIFFE JWT-SVID instead.

Incident response must therefore consider root activation, provider, mapping, service account and the token's short lifetime together. A stolen short-lived token is still sensitive until it expires. A compromised certificate key requires rapid deactivation of the affected trust chain or mapping rule.

A pragmatic migration plan

Do not replace every secret at once. The smallest useful route is:

1. inventory every place OpenAI API keys are stored, copied or loaded at runtime;
2. choose one bounded, non-critical workload;
3. create a dedicated service account and narrow identity mapping;
4. prefer OIDC when the platform already issues verifiable workload tokens; choose X.509 when a well-operated certificate identity exists;
5. implement token exchange, renewal, errors and audit signals;
6. allow parallel operation only for a defined period;
7. revoke the old API key and verify no hidden fallback keeps using it;
8. only then repeat the pattern for other workloads.

The goal is not “no secrets anywhere”. The goal is a machine that proves its identity, receives only the right role and gets access that expires by itself. A lost permanent key becomes a bounded, observable security event rather than a quiet open-ended risk.

Sources

• OpenAI API Changelog: mTLS and X.509 workload identity are GA
• OpenAI: Workload Identity Federation
• OpenAI: Configure X.509 workload identity
• OpenAI: Mutual TLS
• OpenAI: GitHub Actions with Workload Identity Federation