API Gateway mTLS: Client Identity, Certificate Rotation, and APISIX Configuration

Mutual TLS (mTLS) lets the API gateway authenticate a client that presents an X.509 certificate and proves possession of its private key during the TLS handshake, while the client also authenticates the gateway's server certificate. It is a strong machine-to-machine authentication mechanism when the certificate authority, issuance process, identity mapping, and private-key custody are controlled.

mTLS is not complete API authorization. A valid certificate establishes a client identity within a trust domain; route, tenant, action, and object permissions still require explicit policy. Operability also depends on overlap rotation, revocation or short-lived certificates, inventory, monitoring, and safe trust-anchor changes.

Key Takeaways

Define which certificate authority can issue client identities for each hostname and environment.
Map identity from reviewed certificate fields or a registry, not from an arbitrary forwarded header.
Keep authentication, route authorization, and application object authorization distinct.
Rotate client certificates and CA bundles with an overlap window and rollback plan.
Test missing, expired, untrusted, mismatched, and soon-to-expire certificates before production; verify the deployed terminator's revocation behavior or document that it is unavailable.

Place the mTLS Trust Boundary

Decide where TLS terminates and which hop authenticates the client:

flowchart LR
    C[Client with certificate] -->|mTLS| G[API gateway]
    G -->|Authenticated principal and policy| A[Application]
    G -->|Optional separate mTLS| U[Upstream service]
    I[Certificate issuer] --> C
    I --> G

Client-to-gateway mTLS and gateway-to-upstream mTLS are separate connections with separate identities and trust stores. If a CDN or load balancer terminates client mTLS before the gateway, the gateway no longer verifies the original certificate directly. It must trust a protected connection and an authenticated assertion from that exact intermediary, and direct bypass paths must be closed.

Define:

server hostname and certificate ownership;
accepted client CA roots and intermediates;
certificate profile, key usage, subject/SAN convention, and maximum lifetime;
who can issue, renew, revoke, and recover a client identity;
whether certificate identity maps to a workload, organization, device, or integration;
where route and object authorization occur after authentication.

Do Not Confuse a Certificate with Permission

The TLS layer validates a chain to a trusted CA, certificate time validity, and proof of the private key. It does not automatically establish that the principal may call /v1/payments, access tenant A, or modify invoice 123.

Map the verified certificate to a stable internal principal. Prefer a governed SAN profile or registry binding over ad hoc parsing of a free-form common name. Normalize values before comparison, handle renames explicitly, and ensure two issuers cannot create colliding identities.

Then evaluate route- or operation-level authorization at the gateway and resource-level authorization in the service that owns the data. If identity is forwarded upstream, remove any client-supplied copy first and protect the gateway-to-upstream path so the header cannot be forged.

Configure Client Verification in APISIX

The Apache APISIX 3.18 client-to-APISIX mTLS tutorial configures client verification on an SSL resource associated with an SNI. The following excerpt uses placeholders; do not paste private keys into source control:

curl "http://127.0.0.1:9180/apisix/admin/ssls/partner-api" \
  -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "snis": ["partner-api.example.com"],
    "cert": "<server-certificate-chain>",
    "key": "<server-private-key-from-secret-workflow>",
    "client": {
      "ca": "<trusted-client-ca-bundle>",
      "depth": 2
    }
  }'

The SSL resource makes client.ca the trust anchor for client-certificate validation on the associated SNI. Set chain depth to match the intended hierarchy rather than accepting an unnecessarily broad chain. Confirm the exact schema against the documentation for the release you deploy.

APISIX exposes TLS variables such as certificate fingerprint, serial number, subject DN, and the separate verification result in $ssl_client_verify. Its official tutorial demonstrates forwarding certificate attributes with proxy-rewrite. Treat those attributes as identity context only when $ssl_client_verify reports success and the request is on a non-bypassed path. If an upstream needs that context, forward only reviewed fields, use an internal header name, overwrite incoming copies, and restrict the upstream to traffic from the gateway. A raw subject DN is not automatically a canonical account identifier.

Avoid Accidental mTLS Bypasses

APISIX supports skip_mtls_uri_regex on the client-verification configuration. A bypass can be useful for a health or bootstrap endpoint, but it changes the trust boundary for every matching path under the SNI.

Prefer a separate hostname or listener when authenticated and public traffic have materially different trust requirements. If a bypass is unavoidable:

anchor the expression and review percent-encoding, normalization, and path matching;
keep the bypass endpoint unable to reach protected operations;
add separate authentication and rate controls where required;
test near matches and routing changes;
audit every change to the bypass list.

Do not assume route authorization will compensate for an unexpectedly broad TLS bypass unless that behavior is explicitly tested.

Design Certificate Issuance and Rotation

The safest rotation is routine, automated, and observable:

issue a new client certificate through an authenticated enrollment process;
distribute it and its private key through an approved secret or device workflow;
allow an overlap period in which the old and new identities are both recognized;
confirm successful use of the new certificate by principal and client population;
remove or revoke the old certificate according to policy;
record issuer, serial, principal, owner, issuance, expiration, and status in inventory.

For CA rotation, distribute the new trust anchor before issuing clients from it. During the overlap, verify that both chains work and that no unintended issuer is trusted. Remove the old root only after every required client has migrated and a rollback decision has been made.

Short-lived certificates reduce the exposure window when revocation checking is impractical, but they increase dependence on automated issuance. Longer-lived certificates need stronger revocation, inventory, alerting, and emergency replacement processes. Choose deliberately; do not rely on expiry as the only incident response.

Protect Private Keys and Trust Stores

Generate and store private keys in hardware-backed or managed key storage where the risk warrants it.
Prevent export when clients can use a non-exportable key.
Restrict who can change client CAs, server keys, and SSL resources.
Separate production and non-production issuers.
Monitor certificate inventory and alert well before expiration.
Record trust-store and identity-mapping changes as audit events.
Treat a compromised CA as a trust-domain incident, not a single-client rotation.

Never include real keys or certificates from production in tickets, examples, test fixtures, or logs.

Define Failure and Availability Behavior

Without skip_mtls_uri_regex, client-certificate failures normally terminate the TLS handshake before ordinary HTTP request processing. When skip_mtls_uri_regex is configured, APISIX allows the handshake to continue so it can inspect the URI; for a non-bypassed path, a missing or invalid client certificate is then rejected during request processing with HTTP 400. Clients need operational guidance for certificate-required, untrusted-chain, expired-certificate, hostname, and protocol failures without receiving sensitive diagnostic detail from a public endpoint.

Plan for:

certificate issuer and enrollment outages;
expired server or client certificates;
incomplete chains and clock errors;
stale trust bundles across gateway instances;
clients that cannot rotate during the planned window;
emergency removal of one principal or an entire issuer;
capacity and latency effects from TLS handshakes.

Do not create a blanket public fallback that silently removes client authentication during an outage. Recovery should restore trusted identity or move traffic through an explicitly approved alternate boundary.

Test the Complete Lifecycle

Use a staging trust domain and synthetic identities to verify:

a valid client and trusted chain succeed;
no client certificate, an untrusted CA, an expired certificate, and an incomplete chain fail;
the server hostname and chain are verified without insecure client flags;
the mapped principal is stable and cannot be overwritten by a request header;
a valid certificate without permission receives the intended authorization denial;
old and new certificates work during overlap, then the old one stops working;
CA bundle changes reach every gateway instance;
bypass paths match only the intended endpoints;
logs contain useful serial or fingerprint references without private keys or excessive certificate data;
alerts fire before expiry and during abnormal handshake failure rates.

mTLS Readiness Checklist

Where does client TLS terminate, and can traffic bypass that point?
Which issuers, certificate profiles, names, and chain depths are trusted?
How is a verified certificate mapped to one internal principal?
Which permissions remain at the gateway and application layers?
Can clients and CAs rotate with overlap and rollback?
How are compromised, expired, and orphaned certificates removed?
Are private keys non-exportable or otherwise adequately protected?
Are bypass rules narrow, tested, and audited?
Have all negative and lifecycle tests passed without disabling server verification?

Summary

mTLS provides strong client authentication when the gateway controls trust anchors and the client protects its private key. Production safety depends on much more than the handshake: define identity mapping, keep authorization separate, close bypass paths, automate rotation, inventory certificates, and rehearse issuer and client failures. Treat the PKI lifecycle as part of the API platform.

FAQ

Does mTLS replace OAuth or application authorization?

No. mTLS authenticates a certificate holder. OAuth can convey delegated authority, and application policy still decides which resources and actions that principal may access.

Should identity come from the certificate common name?

Only if your certificate profile explicitly governs and uniquely maps that field. A reviewed SAN convention or issuer-backed registry is usually easier to constrain and evolve.

Can an API gateway forward certificate identity in a header?

Yes, after verification, but it must overwrite client-supplied copies and protect the gateway-to-upstream path. The upstream must trust only the gateway as the header source.

Next Steps

Apply fine-grained API gateway authorization after authentication, and measure the handshake path with the API gateway TLS performance guide. For centrally managed gateway security, explore API7 Enterprise.