Authorizers & resource policies

An authorizer checks each caller before a method or route runs. To create one, open the API from APIs, choose Authorizers in the API editor's section list, then New Authorizer. Owners, Admins and Managers can manage authorizers.

1. Type a Name and pick a Type. The type can't be changed later.
2. Under Identity sources, keep the suggested source or type another and choose Add. At least one is required.
3. For JWT, fill in Issuer. For a custom authorizer, pick the Function and its address.
4. Optional: set Result cache TTL (seconds) and Timeout (ms).
5. Choose Create Authorizer.

An authorizer does nothing until a method or route uses it: pick it in the method's or route's authorization settings.

Pods offers three types of authorizer. Which ones an API can use depends on its protocol.

• JWT (OIDC issuer): verifies a signed token from your identity provider. REST and HTTP APIs.
• Custom token: sends one token from the request to your own function, which decides. REST, HTTP and WebSocket APIs.
• Custom request: sends the request's identity sources, such as headers, query strings and stage variables, to your function. REST, HTTP and WebSocket APIs.

On a WebSocket API, an authorizer checks the $connect route, when a client opens its connection.

The list under Configured authorizers shows each one's type, issuer or function address, identity sources, cache TTL and timeout.

A JWT authorizer verifies tokens issued by an OpenID Connect provider. In the authorizer dialog:

• Issuer: required, such as https://issuer.example.com. Pods finds the provider's signing keys from its /.well-known/openid-configuration document.
• Audiences: optional, comma or space separated, up to 50.
• Identity sources: where the token comes from, by default the Authorization header. A leading Bearer is removed.

A token passes when its signature checks out, its iss matches the issuer exactly, it carries an exp that hasn't passed, and its aud or client_id contains one of the audiences, if you set any. Tokens signed with none or an HS algorithm are always rejected.

A missing or invalid token gets 401. When the method or route lists scopes, a valid token without any of them gets 403.

To check a token, choose Debug token in the authorizer's ⋯ menu, paste it and choose Decode. The token is decoded in your browser only, and each check (algorithm, issuer, audience and expiry) shows pass or fail.

A custom authorizer calls your own function to decide. In the authorizer dialog, leave Function on Webhook (any HTTPS endpoint) and type its Webhook URL. Pods sends each check to that address as a POST with a JSON body, and a 401 from it rejects the caller with 401.

• Custom token: one identity source. On a REST API it must be a single header, such as method.request.header.Authorization. Optional: an Identity validation regex; a token that doesn't match is rejected with 401 before your function runs.
• Custom request: one or more identity sources, such as method.request.header.Authorization and context.identity.sourceIp, or $request.querystring.version on HTTP and WebSocket APIs.
• On HTTP APIs, choose the Payload format version your function receives, 1.0 or 2.0 (the default), and turn on Simple responses to have it return { isAuthorized: true | false } instead of a policy.

Otherwise your function returns a policy: a principalId, a policyDocument that allows or denies the call, and an optional context. When an identity source is missing, the caller gets 401 and your function isn't called. A denial gets 403, and a timeout or malformed answer gets 500.

Every authorizer has two limits, set in its dialog.

• Result cache TTL (seconds): from 0 to 3600. Pods remembers each result for that long, keyed by the identity values, so repeat calls skip the check. 0 turns caching off. JWT authorizers and custom authorizers on HTTP APIs start at 0; other custom authorizers start at 300.
• Timeout (ms): from 1000 to 29000, 10000 by default. A function that takes longer fails the call with 500.

A cached policy is still checked against each method, so a policy cached from GET /pets can deny POST /pets. Denials and 401s are cached too; errors aren't.

To test a custom authorizer on a REST API, choose Test in its ⋯ menu in the API editor's Authorizers section.

1. Fill in Headers (JSON), and optionally Query string (JSON) and Stage variables (JSON). Each must be a JSON object.
2. Optional: type a Method ARN to test against, such as one ending in /prod/GET/pets.
3. Choose Run Test.

Result shows whether the call was allowed, the principal, how long it took, and the policy and context your function returned. Log traces the call, with secret values masked. Tests skip the result cache and never touch live traffic. Owners, Admins and Managers can run them.

Click an authorizer, or choose Edit in its ⋯ menu, to change it, then choose Save Changes. Everything except the type can change.

To delete one, choose Delete in its ⋯ menu. Pods asks you to confirm. Methods and routes that used it lose their authorization check, and it can't be undone. Like other changes to the API, edits and deletions reach callers when you next deploy.

Each REST method has an Authorization card in its details under Resources. For an HTTP or WebSocket route, choose Authorization in the route's ⋯ menu under Routes.

• Authorization type: None (open), the default; Signed requests (SigV4), where callers sign each request with one of the project's signing credentials; JWT, not on WebSocket APIs; or Custom authorizer.
• Authorizer: for JWT and Custom authorizer, pick one of the API's authorizers. Pods won't save the type without one.
• Scopes: for JWT, space separated, such as read:pets write:pets. The token must carry at least one.
• API key required: on REST methods and WebSocket routes. Callers must also send a valid API key.

Choose Save Authorization. Owners, Admins and Managers can change it; others see it read-only. Signing credentials are covered in Security, and API keys in Usage plans and API keys.

A resource policy filters calls to a REST API by IP address, connector or signing principal, before any authorizer runs. An explicit Deny always wins. It's in the Resource policy card of the API editor's Settings section, and only Owners and Admins can edit it.

1. Optional: under Start from a template, choose IP allow-list, Deny IP range, Connector-only private API or Cross-project principal allow. The template replaces the editor's text.
2. Edit the JSON in Policy document, up to 8192 characters, with Version and Statement.
3. Choose Save Policy.

A saved policy takes effect on the API's next deployment. Clear removes the policy after you confirm, and from the next deployment callers are no longer filtered.

The Policy simulator, under the resource policy in a REST API's Settings section, checks the saved policy against a sample call. It doesn't need a deployment.

1. In Method ARN, type the call to check, in the form arn:pods:execute-api:auto:{project ID}:{API ID}/{stage}/{method}/{path}.
2. Type a Source IP, and optionally a Principal ARN.
3. Choose Simulate.

The result shows Allow or Deny, and which statements matched.