---
title: "API Gateway mTLS: Client Identity, Certificate Rotation, and APISIX Configuration - API7.ai"
description: "Deploy client-to-gateway mTLS with explicit trust anchors, safe identity mapping, certificate rotation, and tested failure behavior."
url: "https://api7.ai/learning-center/api-gateway-guide/api-gateway-mtls"
---

[Skip to article](#column-content)

Column contentsAPI Gateway Guide

[API Gateway Guide](https://api7.ai/learning-center/api-gateway-guide)

Search this column

01 Gateway Fundamentals

[View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=fundamentals)[1. What Is an API Gateway? API Gateway Software and Use Cases](https://api7.ai/learning-center/api-gateway-guide/what-is-an-api-gateway)[2. Why Do Modern Architectures Need an API Gateway?](https://api7.ai/learning-center/api-gateway-guide/why-do-modern-architectures-need-api-gateway)[3. Reverse Proxy vs Load Balancer vs API Gateway](https://api7.ai/learning-center/api-gateway-guide/api-gateway-vs-reverse-proxy-vs-load-balancer)[4. API Gateway and Microservices: Decoupling and Traffic Management](https://api7.ai/learning-center/api-gateway-guide/api-gateway-and-microservices)[5. Understanding Core API Gateway Features](https://api7.ai/learning-center/api-gateway-guide/core-api-gateway-features)[6. Open Source vs. Commercial API Gateways: How to Choose the Right One?](https://api7.ai/learning-center/api-gateway-guide/open-source-vs-commercial-api-gateway)[7. API Gateway vs Service Mesh: How to Choose?](https://api7.ai/learning-center/api-gateway-guide/api-gateway-vs-service-mesh)[8. Envoy vs NGINX, Java, and Go for API Gateways](https://api7.ai/learning-center/api-gateway-guide/nginx-vs-envoy-vs-java-vs-go)[9. Core Concepts of API Gateway: Service, Route, Upstream, Plugin, and Consumer](https://api7.ai/learning-center/api-gateway-guide/core-concepts-of-api-gateway)[10. API Gateway Comparison: Apache APISIX vs. Kong vs. Traefik vs. KrakenD vs. Tyk](https://api7.ai/learning-center/api-gateway-guide/api-gateway-comparison-apisix-kong-traefik-krakend-tyk)

02 Gateway Architecture and Design

[View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=architecture)[11. Deep Dive into API Gateway Architecture: Core Components and Design Principles](https://api7.ai/learning-center/api-gateway-guide/api-gateway-architecture)[12. Choosing the Right API Gateway for Your Architecture](https://api7.ai/learning-center/api-gateway-guide/api-gateway-monolithic-vs-microservices)[13. How to Architect an API Gateway for High Availability (HA)?](https://api7.ai/learning-center/api-gateway-guide/api-gateway-high-availability)[14. API Gateway Plugin Architecture: How to Extend and Customize Your API Gateway](https://api7.ai/learning-center/api-gateway-guide/api-gateway-plugin-system)[15. How Event-Driven Architecture (EDA) Works with API Gateway?](https://api7.ai/learning-center/api-gateway-guide/api-gateway-event-driven-architecture)[16. API Gateway Request Lifecycle Explained](https://api7.ai/learning-center/api-gateway-guide/api-gateway-request-lifecycle-explained)[17. Cloud-Native API Gateway on Kubernetes](https://api7.ai/learning-center/api-gateway-guide/cloud-native-api-gateway-kubernetes)[18. API Gateway Control Plane vs. Data Plane](https://api7.ai/learning-center/api-gateway-guide/api-gateway-control-plane-vs-data-plane)[19. How API Gateways Work with GitOps: Automating API Management](https://api7.ai/learning-center/api-gateway-guide/api-gateway-gitops-integration)[20. How to Perform A/B Testing and Canary Releases with an API Gateway](https://api7.ai/learning-center/api-gateway-guide/ab-testing-canary-release-api-gateway)

03 Gateway Setup and Traffic Handling

[View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=traffic-protocols)[21. How to Deploy an API Gateway on Kubernetes: Step-by-Step Guide for Engineers](https://api7.ai/learning-center/api-gateway-guide/deploy-api-gateway-on-kubernetes)[22. Hands-on Setup with Apache APISIX API Gateway](https://api7.ai/learning-center/api-gateway-guide/api-gateway-getting-started-guide)[23. API Gateway Auth: OAuth 2.0, JWT & OIDC with APISIX](https://api7.ai/learning-center/api-gateway-guide/api-gateway-authentication-apache-apisix-oauth-jwt-oidc)[24. Mastering Traffic Control: Efficiently Managing API Requests with Gateways](https://api7.ai/learning-center/api-gateway-guide/api-gateway-traffic-control-strategies)[25. Building Reliable API Gateways with Logging and Monitoring](https://api7.ai/learning-center/api-gateway-guide/api-gateway-logging-monitoring-best-practices)[26. Dynamic Routing in API Gateways: Best Practices for Flexible Traffic Management](https://api7.ai/learning-center/api-gateway-guide/api-gateway-dynamic-routing-management)[27. How API Gateways Support WebSocket](https://api7.ai/learning-center/api-gateway-guide/how-api-gateways-support-websocket)[28. API Gateway for GraphQL: Security, Cost, and Caching](https://api7.ai/learning-center/api-gateway-guide/api-gateway-handle-graphql)[29. How API Gateways Handle HTTP/3 QUIC Requests](https://api7.ai/learning-center/api-gateway-guide/api-gateway-http3-quic)[30. How API Gateways Handle MQTT Requests](https://api7.ai/learning-center/api-gateway-guide/api-gateway-mqtt)

04 Gateway Integrations, AI, and MCP

[View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=ai-mcp)[31. How API Gateways Handle gRPC Requests](https://api7.ai/learning-center/api-gateway-guide/api-gateway-grpc-support)[32. How API Gateways Implement Custom Plugins](https://api7.ai/learning-center/api-gateway-guide/api-gateway-custom-plugins)[33. How API Gateways Integrate with Kafka](https://api7.ai/learning-center/api-gateway-guide/api-gateway-kafka-integration)[34. How to Implement API Aggregation in API Gateways](https://api7.ai/learning-center/api-gateway-guide/api-gateway-api-aggregation)[35. How API Gateways Enable Serverless Architecture](https://api7.ai/learning-center/api-gateway-guide/api-gateway-serverless-architecture)[36. How API Gateways Proxy LLM Requests](https://api7.ai/learning-center/api-gateway-guide/api-gateway-proxy-llm-requests)[37. How API Gateways Enhance MCP Servers](https://api7.ai/learning-center/api-gateway-guide/api-gateway-enhance-mcp-server)[38. MCP Gateway vs MCP Proxy vs AI Gateway vs API Gateway](https://api7.ai/learning-center/api-gateway-guide/ai-gateway-vs-mcp-gateway-vs-api-gateway)[39. What Is an AI Gateway? Architecture and Benefits](https://api7.ai/learning-center/api-gateway-guide/what-is-an-ai-gateway)[40. What Is an MCP Gateway? Architecture, Use Cases & How It Works (2026 Guide)](https://api7.ai/learning-center/api-gateway-guide/what-is-mcp-gateway)

05 Gateway Performance

[View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=performance)[41. How API Gateway Reduces Latency: Performance Optimization Strategies](https://api7.ai/learning-center/api-gateway-guide/how-api-gateway-reduces-latency)[42. API Gateway Caching Strategy: Comprehensive Analysis and Implementation Guide](https://api7.ai/learning-center/api-gateway-guide/api-gateway-caching-strategy-analysis)[43. How to Optimize API Gateway Load Balancing: Advanced Strategies and Best Practices](https://api7.ai/learning-center/api-gateway-guide/how-to-optimize-api-gateway-load-balancing)[44. How API Gateway Efficiently Handles Large-Scale Traffic: Architecture and Strategies](https://api7.ai/learning-center/api-gateway-guide/how-api-gateway-handles-large-scale-traffic)[45. How to Improve API Gateway QoS: Traffic Classes, Capacity Protection, and SLOs](https://api7.ai/learning-center/api-gateway-guide/api-gateway-quality-of-service)[46. API Gateway Log Storage: Pipelines, Retention, Security, and Cost](https://api7.ai/learning-center/api-gateway-guide/api-gateway-log-storage)[47. API Gateway Timeouts and Retries: Safe Policies and APISIX Configuration](https://api7.ai/learning-center/api-gateway-guide/api-gateway-timeouts-retries)[48. API Gateway Concurrency Control: Capacity Budgets, Backpressure, and Load Shedding](https://api7.ai/learning-center/api-gateway-guide/api-gateway-concurrency-control)[49. Asynchronous API Gateway Patterns: Queues, Callbacks, and Performance Boundaries](https://api7.ai/learning-center/api-gateway-guide/asynchronous-api-gateway-patterns)[50. API Gateway TLS Performance: Handshakes, Session Reuse, and Measurement](https://api7.ai/learning-center/api-gateway-guide/api-gateway-tls-performance)

06 Gateway Security

[View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=security)[51. DDoS Defense at the API Gateway: Layered Controls and Failure Planning](https://api7.ai/learning-center/api-gateway-guide/api-gateway-ddos-defense)[52. Distributed API Gateway Rate Limiting: Local vs Redis Counters and Accuracy Trade-offs](https://api7.ai/learning-center/api-gateway-guide/distributed-api-gateway-rate-limiting)[53. API Gateway IP Allowlist and Denylist Management: Trust, Proxies, and Operations](https://api7.ai/learning-center/api-gateway-guide/api-gateway-ip-allowlist-denylist-management)[54. API Gateway Security Scanning: What to Test and How to Operationalize Findings](https://api7.ai/learning-center/api-gateway-guide/api-gateway-security-scanning)[55. SQL Injection and XSS at the API Gateway: Detection Limits and Defense in Depth](https://api7.ai/learning-center/api-gateway-guide/sql-injection-xss-api-gateway)[56. API Access Log Auditing: Evidence, Integrity, Retention, and Review](https://api7.ai/learning-center/api-gateway-guide/api-access-log-auditing)[57. Preventing API Scraping and Abuse: Identity, Behavioral Signals, and Rate Controls](https://api7.ai/learning-center/api-gateway-guide/prevent-api-scraping-abuse)[58. API Gateway mTLS: Client Identity, Certificate Rotation, and APISIX Configuration](https://api7.ai/learning-center/api-gateway-guide/api-gateway-mtls)[59. Fine-Grained API Gateway Authorization: RBAC, ABAC, and External Policy Decisions](https://api7.ai/learning-center/api-gateway-guide/fine-grained-api-gateway-authorization)[60. API Gateway and WAF Reference Architecture: Ownership, Header Trust, and Failure Modes](https://api7.ai/learning-center/api-gateway-guide/api-gateway-waf-reference-architecture)

07 Gateway Ecosystem and Comparisons

[View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=ecosystem)[61. Apache APISIX vs Kong: Migration, Operations, and Team Fit](https://api7.ai/learning-center/api-gateway-guide/apache-apisix-vs-kong)[62. Traefik vs Kong vs APISIX: A Reproducible API Gateway Benchmark Method](https://api7.ai/learning-center/api-gateway-guide/traefik-kong-apisix-benchmark-method)[63. Amazon API Gateway Explained: Deployment Models, Trade-offs, and Use Cases](https://api7.ai/learning-center/api-gateway-guide/amazon-api-gateway-explained)[64. API Gateway and Istio: Clear North-South and East-West Boundaries](https://api7.ai/learning-center/api-gateway-guide/api-gateway-istio)[65. API Gateway with NGINX: Layering, Ownership, and Migration Patterns](https://api7.ai/learning-center/api-gateway-guide/api-gateway-nginx)[66. API Gateway with Envoy: Deployment Patterns and Policy Ownership](https://api7.ai/learning-center/api-gateway-guide/api-gateway-envoy)[67. API Gateway with Cloudflare API Shield: Edge and Origin Security Boundaries](https://api7.ai/learning-center/api-gateway-guide/api-gateway-cloudflare-api-shield)[68. Apigee vs MuleSoft vs Amazon API Gateway: A Decision Framework](https://api7.ai/learning-center/api-gateway-guide/apigee-mulesoft-amazon-api-gateway)[69. Should an API Gateway Connect Directly to a Database? Patterns and Risks](https://api7.ai/learning-center/api-gateway-guide/api-gateway-database-access-patterns)[70. API Gateway Architecture for Large-Scale SaaS Platforms](https://api7.ai/learning-center/api-gateway-guide/api-gateway-large-scale-saas-architecture)

08 Industry Applications and Integrations

[View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=applications)[71. API Gateway CI/CD: Validation, Promotion, and Safe Rollback](https://api7.ai/learning-center/api-gateway-guide/api-gateway-ci-cd)[72. API Gateways for AI and ML Inference: Traffic, Security, and Observability](https://api7.ai/learning-center/api-gateway-guide/api-gateways-ai-ml-inference)[73. API Gateway Architecture for Financial Services: Controls and Failure Boundaries](https://api7.ai/learning-center/api-gateway-guide/api-gateway-financial-services)[74. API Gateway Architecture for E-Commerce: Checkout Reliability and Traffic Peaks](https://api7.ai/learning-center/api-gateway-guide/api-gateway-ecommerce)[75. API Gateways for Mobile Applications: Authentication, Payloads, and Versioning](https://api7.ai/learning-center/api-gateway-guide/api-gateways-mobile-applications)[76. API Gateways for Web3 Applications: RPC Traffic, Identity, and Abuse Controls](https://api7.ai/learning-center/api-gateway-guide/api-gateways-web3-applications)[77. OpenAPI-Driven API Gateway Operations: Import, Validation, and Drift Control](https://api7.ai/learning-center/api-gateway-guide/openapi-driven-api-gateway-operations)[78. gRPC-Web and gRPC Transcoding Through an API Gateway](https://api7.ai/learning-center/api-gateway-guide/grpc-web-grpc-transcoding-api-gateway)[79. API Gateway Pricing and Cost Optimization: A Workload-Based Model](https://api7.ai/learning-center/api-gateway-guide/api-gateway-pricing-cost-optimization)[80. Evaluating API Gateway Directions: Evidence and Architectural Impact](https://api7.ai/learning-center/api-gateway-guide/api-gateway-trends)

09 Advanced Gateway Applications

[View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=operations)[81. API Gateways in Zero Trust Architecture: Identity, Policy, and Limits](https://api7.ai/learning-center/api-gateway-guide/api-gateways-zero-trust-architecture)[82. API Gateway Log Analytics: Correlation, Queries, and Operational Signals](https://api7.ai/learning-center/api-gateway-guide/api-gateway-log-analytics)[83. From API Sprawl to Governed Delivery: The Gateway's Role in Modernization](https://api7.ai/learning-center/api-gateway-guide/api-gateway-modernization)[84. API Monetization at the Gateway: Plans, Metering, Entitlements, and Billing Boundaries](https://api7.ai/learning-center/api-gateway-guide/api-monetization-gateway)[85. Safe AI-Assisted API Gateway Optimization: Recommendations, Guardrails, and Approval](https://api7.ai/learning-center/api-gateway-guide/ai-assisted-api-gateway-optimization)[86. API Gateways for Low-Code and No-Code Integration: Governance and Safety](https://api7.ai/learning-center/api-gateway-guide/api-gateways-low-code-no-code-integration)[87. API Gateway and CIAM Integration: Token Validation, Consent, and Identity Context](https://api7.ai/learning-center/api-gateway-guide/api-gateway-ciam-integration)[88. Elastic API Gateway Scaling: Signals, Capacity, and Safe Scale-In](https://api7.ai/learning-center/api-gateway-guide/elastic-api-gateway-scaling)[89. Multi-Tenant SaaS API Gateways: Isolation, Quotas, and Tenant-Aware Policy](https://api7.ai/learning-center/api-gateway-guide/multi-tenant-saas-api-gateway-policy)[90. API Gateway DevSecOps: Policy as Code, Testing, and Runtime Feedback](https://api7.ai/learning-center/api-gateway-guide/api-gateway-devsecops)

10 Platform Engineering and Planning

[View this topic · 10](https://api7.ai/learning-center/api-gateway-guide?topic=platform-governance)[91. API Discovery and Documentation at the Gateway: Inventory, Ownership, and Drift](https://api7.ai/learning-center/api-gateway-guide/api-discovery-documentation-gateway)[92. WebAssembly Plugins for API Gateways: Portability, Isolation, and APISIX Boundaries](https://api7.ai/learning-center/api-gateway-guide/api-gateway-webassembly-plugins)[93. Monitoring API Gateways with Prometheus and Grafana: Metrics, Dashboards, and Alerts](https://api7.ai/learning-center/api-gateway-guide/monitor-api-gateways-prometheus-grafana)[94. API Gateway Reliability Engineering: SLOs, Failure Isolation, and Incident Response](https://api7.ai/learning-center/api-gateway-guide/api-gateway-reliability-engineering)[95. API Gateways for Edge AI Inference: Routing, Constraints, and Observability](https://api7.ai/learning-center/api-gateway-guide/api-gateways-edge-ai-inference)[96. Reducing Cloud Cost with API Gateway Controls: Measurement Before Optimization](https://api7.ai/learning-center/api-gateway-guide/reducing-cloud-cost-api-gateway-controls)[97. Improving API Developer Experience with Gateway Standards and Self-Service](https://api7.ai/learning-center/api-gateway-guide/improving-api-developer-experience-gateway-self-service)[98. API Gateway Change Management: Compatibility, Progressive Delivery, and Rollback](https://api7.ai/learning-center/api-gateway-guide/api-gateway-change-management-rollback)[99. Operating Serverless APIs: Cold Starts, Idempotency, and Asynchronous Handoffs](https://api7.ai/learning-center/api-gateway-guide/operating-serverless-apis-gateway)[100. Planning an API Gateway Roadmap for the Next Five Years](https://api7.ai/learning-center/api-gateway-guide/planning-api-gateway-roadmap-next-five-years)

[API Gateway Guide](https://api7.ai/learning-center/api-gateway-guide)[Gateway Security](https://api7.ai/learning-center/api-gateway-guide?topic=security)

On this page

On this page

- [Key Takeaways](#key-takeaways)

- [Place the mTLS Trust Boundary](#place-the-mtls-trust-boundary)

- [Do Not Confuse a Certificate with Permission](#do-not-confuse-a-certificate-with-permission)

- [Configure Client Verification in APISIX](#configure-client-verification-in-apisix)

- [Avoid Accidental mTLS Bypasses](#avoid-accidental-mtls-bypasses)

- [Design Certificate Issuance and Rotation](#design-certificate-issuance-and-rotation)

- [Protect Private Keys and Trust Stores](#protect-private-keys-and-trust-stores)

- [Define Failure and Availability Behavior](#define-failure-and-availability-behavior)

- [Test the Complete Lifecycle](#test-the-complete-lifecycle)

- [mTLS Readiness Checklist](#mtls-readiness-checklist)

- [Summary](#summary)

- [FAQ](#faq)

  - [Does mTLS replace OAuth or application authorization?](#does-mtls-replace-oauth-or-application-authorization)
  - [Should identity come from the certificate common name?](#should-identity-come-from-the-certificate-common-name)
  - [Can an API gateway forward certificate identity in a header?](#can-an-api-gateway-forward-certificate-identity-in-a-header)

- [Next Steps](#next-steps)

Article 58

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

API7.ai

September 10, 2026

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](https://apisix.apache.org/docs/apisix/tutorials/client-to-apisix-mtls/) 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:

1. issue a new client certificate through an authenticated enrollment process;
2. distribute it and its private key through an approved secret or device workflow;
3. allow an overlap period in which the old and new identities are both recognized;
4. confirm successful use of the new certificate by principal and client population;
5. remove or revoke the old certificate according to policy;
6. 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:

1. a valid client and trusted chain succeed;
2. no client certificate, an untrusted CA, an expired certificate, and an incomplete chain fail;
3. the server hostname and chain are verified without insecure client flags;
4. the mapped principal is stable and cannot be overwritten by a request header;
5. a valid certificate without permission receives the intended authorization denial;
6. old and new certificates work during overlap, then the old one stops working;
7. CA bundle changes reach every gateway instance;
8. bypass paths match only the intended endpoints;
9. logs contain useful serial or fingerprint references without private keys or excessive certificate data;
10. 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](https://api7.ai/learning-center/api-gateway-guide/fine-grained-api-gateway-authorization) after authentication, and measure the handshake path with the [API gateway TLS performance guide](https://api7.ai/learning-center/api-gateway-guide/api-gateway-tls-performance). For centrally managed gateway security, [explore API7 Enterprise](https://api7.ai/enterprise).

[Previous article**Preventing API Scraping and Abuse: Identity, Behavioral Signals, and Rate Controls**](https://api7.ai/learning-center/api-gateway-guide/prevent-api-scraping-abuse)[Next article**Fine-Grained API Gateway Authorization: RBAC, ABAC, and External Policy Decisions**](https://api7.ai/learning-center/api-gateway-guide/fine-grained-api-gateway-authorization)

On this page

- [Key Takeaways](#key-takeaways)

- [Place the mTLS Trust Boundary](#place-the-mtls-trust-boundary)

- [Do Not Confuse a Certificate with Permission](#do-not-confuse-a-certificate-with-permission)

- [Configure Client Verification in APISIX](#configure-client-verification-in-apisix)

- [Avoid Accidental mTLS Bypasses](#avoid-accidental-mtls-bypasses)

- [Design Certificate Issuance and Rotation](#design-certificate-issuance-and-rotation)

- [Protect Private Keys and Trust Stores](#protect-private-keys-and-trust-stores)

- [Define Failure and Availability Behavior](#define-failure-and-availability-behavior)

- [Test the Complete Lifecycle](#test-the-complete-lifecycle)

- [mTLS Readiness Checklist](#mtls-readiness-checklist)

- [Summary](#summary)

- [FAQ](#faq)

  - [Does mTLS replace OAuth or application authorization?](#does-mtls-replace-oauth-or-application-authorization)
  - [Should identity come from the certificate common name?](#should-identity-come-from-the-certificate-common-name)
  - [Can an API gateway forward certificate identity in a header?](#can-an-api-gateway-forward-certificate-identity-in-a-header)

- [Next Steps](#next-steps)
