Zero trust API design

Principles

Assume a network location alone does not make a request trustworthy. Authenticate protected calls, authorise access to the requested resource, encrypt traffic, and limit abuse at appropriate boundaries. A deliberately anonymous endpoint still needs a documented access policy and monitoring.

Authentication patterns

• Use OAuth2/OIDC for user-facing flows; rotate refresh tokens and enforce MFA for admins.
• Use mTLS or workload identities for service-to-service calls.
• Bind scopes to operations in your OpenAPI file; avoid catch-all scopes.

Authorization and access control

Prefer role- or attribute-based access control with least privilege. Document which claims are required per endpoint. Use resource-scoped tokens and enforce audience and issuer checks.

Define a trust boundary for each request

Draw the path from client to gateway, service, and data store. At each hop, decide which identity is presented, who validates it, and which permissions are checked. A gateway can reject an invalid token, but the application may still need to decide whether that user owns an order or may change an account setting. Do not assume a call from an internal subnet is automatically safe; service identities and policies should be explicit.

For a public read operation, document why anonymous access is allowed and what data it can return. For a protected operation, declare the security scheme in OpenAPI and test that the service rejects missing and invalid credentials. A static scan can identify a missing declaration; it cannot prove that every hop validates the caller correctly.

Apply least privilege to users and services

Give a service only the operations and data it needs. A token issued for reporting should not also allow account administration. Check issuer, audience, expiry, and intended permission at the receiving service. A broad scope is easier to configure, but it increases the impact of a leaked credential. Rotate service credentials and remove unused grants when an integration is retired.

Object ownership is separate from a role or scope. A user with permission to read invoices may still be limited to invoices in their organisation. Test with two tenants and at least two roles, including nested resources and exports. The OAuth2 and JWT guide covers token validation; the public API guide covers internet-facing access decisions.

Plan for a compromised identity

Decide how quickly a stolen token or key can be revoked, how affected users are identified, and which operations will be blocked during an incident. Short access-token lifetimes reduce the window of use, while narrow permissions reduce the damage a token can cause. Keep sensitive actions observable with request IDs and a clear owner. Avoid logging raw credentials, even when debugging an authorization failure.

Review unusual request patterns, repeated denied operations, and sudden changes in volume. These signals can indicate misuse, but they need context; a new integration may create a similar spike. Give responders a way to compare behaviour with the expected contract and to disable a credential without disabling unrelated clients. A zero-trust design is useful when it can be tested and operated, not merely drawn in a diagram.

Verify policy continuously

Run contract checks when security requirements change, and run integration tests against the deployed service. Verify that anonymous access is limited to intended routes, a wrong-audience token is rejected, and cross-tenant resource requests fail. Confirm that a permission removed from a role no longer works after caches refresh. Review gateway and application policies together when adding a new endpoint.

Use rate limits and anomaly detection as supporting controls, not substitutes for authorization. A rate limit can slow abuse but cannot make an exposed private record safe. Scan the OpenAPI file with APISAST for missing security declarations and risky design signals, then use runtime tests for the actual decision at each request.

Verification and monitoring

Add rate limits and anomaly detection at the edge. Return RFC 7807 errors so clients get consistent responses. Scan specs with the static API security scanner to catch missing security schemes.

Review denied requests by route and identity, then test whether a legitimate role change takes effect as expected. Keep the contract, gateway, and service policy aligned during deployments. If a route is intentionally public, document that choice and add abuse controls suited to anonymous callers.

Revisit the policy when ownership or data sensitivity changes.