mTLS and API authorization: document the trust boundaries
A fictional API flow shows what a client certificate establishes and which authorization decisions still need documentation.
AI-assisted article. Sources and examples follow our editorial policy.
“The API uses mTLS” is an incomplete access-control explanation. A reader still needs to know which connection authenticates the client, what identity the application uses, and how it decides whether that identity can perform a requested operation.
Documentation for mTLS API authorization should trace those decisions across the actual deployment. A certificate can participate in authenticating a client or binding a token to a holder. The application still needs an authorization policy for the protected resource.
The worksheet below follows a fictional findings-export API through a gateway. It is a conceptual example, not a deployment recommendation or tested configuration. Different OAuth profiles and TLS termination arrangements require different implementation details.
Separate the mechanisms in the design
RFC 8705 specifies OAuth mutual-TLS client authentication and certificate-bound access tokens. These are distinct mechanisms that can be used together. Documentation should state which one an integration implements instead of using “mTLS” as shorthand for both.
In mutual-TLS client authentication at a token endpoint, the authorization server uses the configured method to authenticate the OAuth client. With certificate-bound access tokens, a resource server verifies the relationship between the token and the certificate presented by the caller under the specified mechanism.
The second mechanism limits use of a token to the corresponding certificate holder within that scheme. It does not establish that every request from that holder is permitted. Scope, audience, resource ownership, tenant boundaries, and application policy still need explicit treatment where applicable.
Avoid copying a single certificate-trust recipe into every explanation of the RFC. It supports distinct authentication methods, including a self-signed certificate method with its own registration assumptions. Describe the selected profile and trust configuration accurately.
Trace one request across the boundaries
In the fictional design, a workload obtains an access token, then requests an export of findings from workspace example-workspace-4. A gateway terminates the external TLS connection before forwarding the request to the API service.
| Boundary | Question the documentation must answer | Required design evidence |
|---|---|---|
| Workload to token endpoint | How is this OAuth client authenticated? | Selected authentication method and registered client configuration |
| Token issuance | Which client, resource, and permissions does the token represent? | Token profile and authorization-server policy |
| Workload to gateway | Which certificate was presented and accepted? | TLS termination and client-certificate verification configuration |
| Gateway token handling | Where is certificate binding checked, if used? | Resource-server enforcement design |
| Gateway to API | How does verified identity reach the application? | Protected forwarding path and trusted identity representation |
| API to workspace data | May this principal export this workspace’s findings? | Resource-specific authorization decision |
| Audit trail | Can an operator trace the decision? | Correlated identity, resource, action, and outcome records |
This worksheet intentionally contains questions rather than a universal architecture. A deployment might terminate TLS at the API instead. The point is to identify the enforcing component for every claimed guarantee.
The OWASP REST Security Cheat Sheet provides related guidance on HTTPS, token validation, and access control. Use it to support a review of the API design, then document the product’s actual behavior.
Review what changes at the proxy
TLS termination creates a boundary that diagrams often obscure. The API service may receive a new connection from the gateway rather than the client’s original TLS session. It cannot infer the original client’s certificate merely from having a TLS connection to the gateway.
If the gateway forwards identity information, document how the receiving service knows that information is trustworthy. Consider whether clients can supply similarly named headers, whether the gateway replaces or rejects them, and whether the application accepts requests that bypass the gateway.
A statement such as “the API checks the client certificate” is misleading if the API actually trusts a gateway assertion. The latter can be a deliberate design, but its trust assumptions should be visible. Do not recommend accepting arbitrary client-controlled forwarding headers as identity evidence.
For a writer, the useful artifact is an annotated request path showing where validation occurs. The API-security overview gives surrounding context for access-control failures, but the product article should stay specific to its own path.
Show an authorization decision that can deny access
An example is clearer when authentication succeeds and authorization fails. In this fictional scenario, the workload presents the expected certificate and a token valid for the API, but its granted permissions allow reading findings only in example-workspace-9.
The request targets example-workspace-4. The application should evaluate its resource policy and deny that request under the fictional contract. The successful connection does not erase the tenant boundary.
Document which component selects the tenant, which identifier the policy evaluates, and how the request’s target is related to the authenticated principal. A permissions list alone does not explain object-level access. Nor does a generic “authenticated” flag establish authority to export every customer’s data.
This is related to the delegation questions in AI-agent authorization, but the same reasoning applies to ordinary service-to-service clients.
Include certificate and token lifecycle behavior
Certificates and tokens have their own lifetimes. RFC 8705 discusses implications of certificate renewal for certificate-bound tokens. A deployment guide should explain what callers do when the certificate changes, which tokens remain usable, and how failures surface.
Avoid promising immediate access removal from certificate rotation alone. The outcome depends on the selected authentication mechanism, token binding, validation behavior, and operational controls. Ask the implementation owner to define the relevant revocation or replacement procedure.
The guide should also identify who owns issuance, renewal, trust configuration, and incident response. A reader needs to know whether an expired certificate is a workload configuration problem, a gateway trust problem, or a token-binding mismatch before choosing a recovery action.
Keep the product claim tied to the flow
A defensible product explanation might say: “The gateway verifies the configured client-certificate relationship and token requirements. The API then evaluates workspace permissions for each export request.” That statement is suitable only when the implementation actually follows it.
During a technical-content review, compare every verb with its enforcing component. Check where identity is established, where certificate binding is evaluated, and where resource access can be denied. If the team cannot identify that component, the documentation needs a narrower claim or an engineering answer before publication.