API Gateway Auth: The Pattern That Did Not Leak

Auth is the one place I cannot afford to get wrong. Most of my serverless work sits behind API Gateway, which offers three main auth patterns. I have used each in production. Here is what I recommend after six months, and what I wish someone had told me on day one.

The Three Patterns

API Gateway supports three main auth mechanisms:

1. IAM auth: for service-to-service calls, uses AWS SigV4
2. Cognito authorizers: for user auth backed by Cognito user pools
3. Lambda authorizers: a custom Lambda that returns allow/deny

My rule is simple. Use IAM for services, Cognito for end users, Lambda authorizers only when neither fits. Most projects only need one. Mixing them is usually a sign the architecture is drifting.

The Lambda Authorizer Trap

Lambda authorizers are flexible, and that flexibility is the problem. I wrote one once that validated JWTs against an external identity provider. It worked. But every request to every endpoint now depended on that Lambda being fast, that IdP being up, and that JWT library being current. When any of those broke, the whole API went down.

I replaced it with a Cognito user pool that federated to the same IdP. Cognito handles the token validation, API Gateway trusts Cognito, my Lambdas see a clean claims object. Fewer moving parts, better failure mode.

The Policy Cache

If you do need a Lambda authorizer, set the policy cache TTL. Without caching, every single API call invokes your authorizer Lambda. With a 300-second cache, a user's first request validates, the next five minutes hit the cache:

authorizer:
  type: REQUEST
  identitySource: method.request.header.Authorization
  resultTtlInSeconds: 300

That single line cut my authorizer invocations by about 95%. Almost free money.

What Did Not Leak

After six months, no auth leaks. A few things contributed:

• Every endpoint requires auth by default, public is opt-in and explicit
• Tokens are validated at the gateway, not in the Lambda, so a buggy Lambda cannot bypass
• Claims are logged but the full token is never logged
• Test suite includes unauthenticated-request checks for every endpoint

None of that is fancy. It is the floor. If you do not have all four, you are one mistake away from a bad day.

See the API Gateway auth documentation for full details.