API Gateway REST APIs get a native JWT authorizer: how to set it up vs Lambda authorizers

API Gateway REST APIs now validate JWTs from Okta, Auth0, Entra ID and Cognito natively. Setup steps, claim rules, 401 vs 403, and when to keep Lambda.

Sanchana Charles18 November 202611 min read0 viewsAWS
API Gateway REST APIs get a native JWT authorizer: how to set it up vs Lambda authorizers

Amazon API Gateway REST APIs now have a native JWT authorizer. AWS announced it on 17 November 2026. API Gateway can now check tokens from Okta, Auth0, Microsoft Entra ID, Amazon Cognito or any other OpenID Connect/OAuth 2.0 provider by itself, so you don't have to write and run a Lambda authorizer to do it. It works on Regional, edge-optimized and private REST APIs in all commercial AWS Regions and AWS GovCloud (US).

In AWS's words: "You now configure token validation instead of writing and operating code for it." Here's how it works, how to set it up, the limits and when you still need a Lambda authorizer.

What is the new API Gateway REST API JWT authorizer?

A JWT authorizer validates the JSON Web Token a client sends, usually in the Authorization header, inside API Gateway before the request reaches your backend. You declare:

  • the issuers you trust (up to 10 per authorizer, according to the AWS Compute Blog),
  • the audiences you accept from each issuer,
  • the signing algorithms you allow (defaultAlgorithms, which is required), and
  • optional claim rules a token must satisfy.

Each method can then require its own scopes. For example, GET /orders can require orders:read and POST /orders can require orders:write, both using the same authorizer.

Why this matters: until now, REST APIs' built-in authorizer accepted only Amazon Cognito tokens. AWS's blog says teams using any other OIDC provider had to write a Lambda authorizer that "fetched signing keys, verified tokens, and returned an IAM policy." HTTP APIs have had a native JWT authorizer for years. REST APIs, which have features like private endpoints, are now catching up.

How does the JWT authorizer validate a request?

According to the API Gateway developer guide, API Gateway:

  1. Reads the token from the header you set as the identity source. The value can be the bare token or Bearer <token>, and the prefix isn't case-sensitive.
  2. Matches the token's iss claim to one of your configured issuers and rejects unknown issuers.
  3. Verifies the signature against the issuer's public keys, which it finds through the issuer's OIDC discovery document at /.well-known/openid-configuration.
  4. Checks aud against your audiences. For Cognito access tokens, it checks client_id instead. It also checks exp, nbf and iat, allowing 60 seconds of clock skew.
  5. Evaluates your additional claim rules.
  6. If the method requires scopes, checks that the token's scope or scp claim contains at least one of them.
  7. Passes the token's claims to your integration as $context.authorizer.claims.

What clients see when it fails:

Problem Response
Missing, malformed, expired or untrusted token 401 Unauthorized
Valid token, but missing a required scope or failing a claim rule 403 Forbidden
Issuer's key endpoint unreachable and no cached keys 5xx (the request is not let through)

Rejected requests never reach your integration.

Which signing algorithms and identity providers are supported?

Algorithms: RS256, RS384, RS512, ES256, ES384 and ES512. API Gateway rejects HMAC-signed tokens such as HS256, as well as alg: none.

Providers: any OIDC/OAuth 2.0 provider whose discovery document and key set are reachable from the public internet, including for private APIs. Their certificates must come from a certificate authority API Gateway supports. AWS's blog walks through Okta, Auth0 and Microsoft Entra ID, then adds Amazon Cognito as a second issuer. Provider quirks from that walkthrough:

  • Auth0: the issuer includes a trailing slash, and Auth0 requires the audience parameter in token requests.
  • Okta: the issuer is based on the authorization server, and the audience is that server's Audience setting.
  • Entra ID: uses the tenant's v2.0 endpoint. Client-credentials tokens carry app roles rather than scopes, so plan your authorization model around that.
  • Cognito: the issuer is https://cognito-idp.{region}.amazonaws.com/{user-pool-id}, the app client ID is the audience, and scopes look like orders/orders:read.

The single most common error in AWS's troubleshooting table is an issuer mismatch. The configured issuer must match the token's iss exactly, including any trailing slash.

How do you set up a JWT authorizer on a REST API?

In the console (per the developer guide):

  1. Open the API Gateway console and choose your REST API.
  2. Go to Authorizers → Create authorizer, enter a name and set Authorizer type to JWT.
  3. Set Identity source to the header that carries the token, such as Authorization.
  4. Select the allowed signing algorithms.
  5. Under Issuers, add each issuer URL (an absolute HTTPS URL that matches iss) and its accepted audiences. Optionally add claim rules.
  6. Under Resources, choose a method, then Method request → Edit, and select your JWT authorizer under Authorization. Optionally add Authorization scopes.
  7. Deploy the API to a stage. AWS's docs say: "Changes to a method take effect only after you deploy the API."

With the AWS CLI: you create the authorizer with aws apigateway create-authorizer --type JWT, passing --identity-source method.request.header.Authorization and --jwt-configuration file://jwt-config.json, according to the AWS Compute Blog. You then attach it per method. This is the exact example from AWS's documentation, which requires the orders:read scope on GET:

aws apigateway put-method \
    --rest-api-id api-id \
    --resource-id resource-id \
    --http-method GET \
    --authorization-type JWT \
    --authorizer-id authorizer-id \
    --authorization-scopes orders:read

Run it again with --http-method POST and --authorization-scopes orders:write for the write method. The console, AWS SDKs, CloudFormation and OpenAPI definitions are also supported.

Two CLI gotchas from AWS's blog: update-authorizer replaces the whole configuration, so always send the full file. And if you rebuild that file from get-authorizer, remove the jwksUri fields first, because API Gateway rejects updates that include them.

What are claim rules and how many can you add?

Claim rules let you require extra claims beyond the standard ones. Per the docs:

  • Up to 10 claim rules per issuer.
  • Each rule uses the SINGLE_STRING format with at most one expected value. Matching is exact and case-sensitive.
  • You can't write rules for iss, aud, exp, nbf, iat, scope or scp.
  • A claim that's an array (for example "groups": ["admins","users"]) fails a rule and gets a 403.
Required? Expected value? Behaviour
Yes No Claim must exist; value isn't checked
Yes Yes Claim must exist and match exactly
No Yes Value is checked only if the claim is present
No No Not checked

If you need to check group arrays, ranges, tenant lookups or anything else, that's still a job for a Lambda authorizer.

JWT vs Cognito vs Lambda authorizer: which should you use?

You need to… Use
Accept tokens from Okta, Auth0, Entra ID or several IdPs at once JWT authorizer
Accept tokens from any app client in your Cognito user pools without listing client IDs Cognito user pool authorizer
Check array claims, call a database, introspect opaque tokens, or accept non-JWT credentials Lambda authorizer
Migrate from one IdP to another without downtime JWT authorizer with both issuers configured during the switch
Mix approaches in one API Allowed: each method uses whichever authorizer you attach

The cost angle is our analysis, not an AWS figure. Moving token validation into the gateway removes Lambda authorizer invocations, along with their code, dependencies and cold starts, from the request path. Neither the announcement nor the documentation pages we read list a separate charge for the JWT authorizer. Normal REST API request pricing still applies; AWS's pricing page examples use $3.50 per million REST API calls. Check the API Gateway pricing page for your Region and volume tier.

How do you read JWT claims in your backend?

API Gateway exposes top-level claims as $context.authorizer.claims.<name>, with each value as JSON. The string "42" and the number 42 stay distinct.

  • Lambda proxy integrations receive them in requestContext.authorizer.claims, keeping their JSON types.
  • Mapping templates can reference them directly. AWS says not to wrap them in quotes or $util.escapeJavaScript().
  • HTTP proxy integrations don't forward claims automatically. Map a claim to a request header, for example integration.request.header.x-roles set to context.authorizer.claims.roles.
  • Nested claims can't be referenced directly. $context.authorizer.claims.address.city isn't valid. Pass address and parse it.

Key rotation: API Gateway caches each issuer's signing keys for up to 1 hour on a best-effort basis, and re-fetches when it sees a key ID it doesn't recognise. Publish new keys before you sign with them, and keep old keys published until the tokens they signed have expired.

What are developers saying?

The feature is a day old, and we didn't find substantial Reddit or re:Post discussion yet, so we have no community quotes to share. The questions developers are searching for are clear from Google's autocomplete: "api gateway rest api jwt authorizer" and "aws api gateway rest api jwt authorizer", both long-standing searches that until now led to HTTP API docs or Lambda authorizer tutorials. If you were one of those people, this is the feature you were looking for.

Editor's take

This removes one of the oldest bits of boilerplate on AWS. Almost every team that put Okta or Auth0 in front of a REST API ended up with a small Lambda that fetched JWKS, cached keys, checked aud and returned a policy, and then had to patch, monitor and keep it warm. A native authorizer with multi-issuer support, per-method scopes and the right 401/403 split is simply better for the common case. The limits are deliberate: single-string claim rules, no arrays, and top-level claims only. Anything clever still belongs in Lambda. Our advice: replace Lambda authorizers that only validate tokens, keep the ones that make real authorization decisions, and test your issuer string (that trailing slash!) before you deploy. Pair it with Cognito's token exchange for AI agents if you're building agent-facing APIs, and see our AWS Interconnect–Azure guide if your Entra ID–protected workloads also span both clouds. (Analysis based on AWS documentation, not hands-on testing.)

FAQ

Does API Gateway REST API support JWT authorizers?

Yes. Since 17 November 2026, REST APIs (Regional, edge-optimized and private) support a native JWT authorizer in all commercial AWS Regions and AWS GovCloud (US).

How do I add a JWT authorizer to an AWS API Gateway REST API?

Create an authorizer of type JWT, add your issuer URL, audiences and allowed algorithms, attach it to each method, optionally with scopes, then deploy the API to a stage.

What is the difference between a JWT authorizer and a Lambda authorizer?

A JWT authorizer validates tokens inside API Gateway with no code. A Lambda authorizer runs your function, so use it for custom logic, array claims, token introspection or non-JWT credentials.

Can API Gateway validate Auth0 or Okta tokens without Lambda?

Yes. AWS's walkthrough configures Okta and Auth0 as issuers. Remember that Auth0's issuer ends with a trailing slash.

Does the REST API JWT authorizer work with Microsoft Entra ID?

Yes. Use the tenant's v2.0 issuer. AWS notes that Entra ID client-credentials tokens carry app roles rather than scopes.

Why does my API Gateway JWT authorizer return 401?

Usually the configured issuer doesn't exactly match the token's iss (often a trailing slash), the token has expired, or it's signed with an algorithm you didn't allow. A 403 means the token was valid but lacked a required scope or failed a claim rule.

Does the REST API JWT authorizer work with private APIs?

Yes. Your identity provider's discovery document and key set must still be reachable from the public internet.

How many issuers can one JWT authorizer trust?

Up to 10 issuers, according to AWS's Compute Blog, with up to 10 claim rules per issuer according to the developer guide.

Sources

Featured image: attendees at a technical session at AWS Summit Mumbai 2026, not an API Gateway launch event. Photo: Zaidusyy, CC BY-SA 3.0, via Wikimedia Commons. Source

Share:

Comments

Leave a comment