The Auth Matrix

Every REST route (or fat-lambda sub-route) picks an authorizer, and may additionally require an API key. The framework never deploys a route open by accident — iam and custom wire real authorizers, and an under-specified custom route throws at synth rather than deploying public.

The five REST modes

Mode	Config	What it does
cognito	authorizer: "cognito" (default)	Cognito User Pool JWT in the Authorization header
none	authorizer: "none"	Public — no authorizer
iam	authorizer: "iam"	AWS IAM (SigV4-signed) — machine-to-machine
custom	authorizer: "custom"	A Lambda (REQUEST) authorizer you supply
API key	apiKey: true (orthogonal)	Requires an x-api-key header

apiKey is orthogonal — a route can be both cognito and apiKey: true.

Wiring one of each

// POST /items — cognito AND an API key (orthogonal)
{ method: "POST", path: "/items", authorizer: "cognito", apiKey: true }

// GET /items — IAM (SigV4-signed)
{ method: "GET", path: "/items", authorizer: "iam" }

// GET /admin/stats — custom Lambda authorizer
{ method: "GET", path: "/admin/stats", authorizer: "custom" }

The custom route needs one backing authorizer Lambda, supplied once per API on the stack (not per route), via a kind:"authorizer" config passed as lambdaAuthorizer. A custom route with no lambdaAuthorizer supplied throws at synth.

API keys never reach SSM

When any route sets apiKey: true, the framework mints one ApiKey + one minimal UsagePlan and binds the key to the stage (REST keys are inert without a usage plan). The key value is never written to SSM — fetch it after deploy with aws apigateway get-api-key --api-key <id> --include-value.

HTTP v2 differences

HTTP API v2 has the same matrix minus native API keys: jwt | lambda | iam | none, with cognito → jwt and custom → lambda. See HTTP v2 API.

Picking it at create time

A composer project selects the access shape once and reconciles every route to match:

axs new my-api --composer --template rest-v1 --api-access authenticated --authorizer cognito
axs new my-api --composer --template rest-v1 --api-access public
axs new my-api --composer --template rest-v1 --api-access mixed --api-key

Under --yes, an API surface with no auth flag errors rather than defaulting to public.