Architecture pattern
Zero-trust API security
Authenticate and authorise every call, at the edge with OAuth and OIDC tokens and between services with mutual TLS, instead of trusting anything inside the network.
- Caller
- Gateway
- Component you run
- Control, identity or policy
- Request
- Configuration or credentials
How it flows
- Client app and Partner system to Identity providerEach caller gets a short-lived access token: people through the authorisation code flow with PKCE, systems through the client credentials grant.
- Client app and Partner system to Edge gatewayCalls the API with the bearer token.
- Edge gateway to Identity providerThe gateway validates signature, expiry, audience and scopes using the provider’s published keys.
- Edge gateway to Orders serviceForwards over mutual TLS, passing verified identity claims.
- Orders service to Payments serviceService-to-service call over mutual TLS. Payments authorises the calling workload, not just the network.
- Workload CA to Edge gateway, Orders service and Payments service (control)Issues short-lived certificates that rotate automatically.
The problem
Perimeter security assumes that anything inside the network is friendly. Once an attacker, a misconfigured service or a compromised dependency is inside, every internal API is open to it. Shared API keys and long-lived certificates make it worse: they leak, and nobody knows who used them.
When to use it
- APIs carry sensitive data or money, or fall under regulation such as PSD2, HIPAA or DORA.
- Many teams own services, so you cannot rely on every one getting security right in code.
- Partners and third parties call your APIs.
- You are moving to Kubernetes or multiple clouds, where network location says little about identity.
When not to
- As a one-off project. Zero trust is an operating model; without certificate automation and token lifecycle management it decays.
- Where a simpler control meets the risk, for example an internal read-only API with no sensitive data. Apply the same principles, but proportionately.
Key components
- Identity provider. Issues OAuth 2.0 access tokens and OIDC identity tokens to users and machines, with short lifetimes and clear scopes.
- Edge gateway. Validates tokens (signature, expiry, audience, scopes) before any request reaches a service, and applies rate limits per identity.
- Mutual TLS between workloads. Every service presents a certificate, so both sides know who they are talking to.
- Workload certificate authority. Issues short-lived certificates and rotates them automatically, often through a service mesh or SPIFFE-style identities.
- Fine-grained authorisation. Each service checks the caller and the action, using claims passed from the edge or a policy engine.
Trade-offs
- Operational load. Certificate issuance, rotation and revocation must be automated. Manual certificate management at this scale fails.
- Latency. Token validation and TLS handshakes add small costs. Local token validation with cached signing keys, and connection reuse, keep them low.
- Debugging. Failed handshakes and expired tokens are harder to diagnose than open networks. Invest in clear error logging and tracing.
- Token design. Large tokens with many claims slow every hop; tokens with too few claims force extra lookups. Agree a standard set early.
Explore further
Lab: One request, eight plugins.→Follow a single AI request through an ordered chain of gateway plugins, switch any of them off and see what changes.