> For the complete documentation index, see [llms.txt](https://docs.serverlessapigateway.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.serverlessapigateway.com/configuration/authorizer.md). # Authorizer The authorizer section configures how the gateway validates bearer tokens before a protected route reaches its upstream service. If you searched for `ERR_JWS_SIGNATURE_VERIFICATION_FAILED`, `JWT claim validation failed`, or other gateway JWT errors, this page is the starting point. Serverless API Gateway currently supports JWT (JSON Web Token) based authorization with HS256 and also documents provider-backed flows such as Auth0 and Supabase elsewhere in the docs. > Serverless API Gateway now support Auth0. Check its integration [page](/configuration/auth0.md). Use the authorizer when a route should reject invalid bearer tokens before the request reaches an upstream service. Public routes such as health checks can stay unauthenticated, while private routes opt into authorization through route configuration. * `type`: Type of authorization (e.g., JWT). * `secret`: Secret key for authorization. * `algorithm`: Algorithm used for token validation. * `audience`: Intended audience of the token. * `issuer`: The issuer of the token. **Example** ``` { "authorizer": { "type": "jwt", "secret": "{YOUR_SECRET_KEY}", "algorithm": "HS256", "audience": "opensourcecommunity", "issuer": "serverlessapigw" }, } ``` ## Quick Fix Checklist Use this checklist before debugging deeper JWT failures: | Check | What to verify | Why it matters | | ---------------------- | ---------------------------------------------- | ------------------------------------------------------ | | Signing secret or key | Matches the token issuer | Prevents signature failures | | `issuer` | Matches the token `iss` claim exactly | Prevents claim validation errors | | `audience` | Matches the token `aud` claim exactly | Prevents claim validation errors | | Token expiration | `exp` is still valid | Prevents `ERR_JWT_EXPIRED` | | Protected route config | Route actually has `auth: true` where expected | Prevents false assumptions about gateway auth behavior | ### JWT Error Serverless API Gateway uses [JOSE JWT](https://github.com/panva/jose) and error states implemented with its error types. Example response: ```json { "error": "Signature verification failed", "code": "ERR_JWS_SIGNATURE_VERIFICATION_FAILED" } ``` Most production JWT failures fall into one of four buckets: | Error code | Common cause | First thing to check | | --------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------- | | `ERR_JWS_SIGNATURE_VERIFICATION_FAILED` | Token was signed with a different secret or key. | Confirm the gateway secret matches the issuer. | | `ERR_JWT_CLAIM_VALIDATION_FAILED` | `issuer`, `audience`, or another claim does not match config. | Compare configured issuer/audience with the token payload. | | `ERR_JWT_EXPIRED` | Token `exp` is in the past. | Refresh or mint a new token. | | `ERR_JWKS_NO_MATCHING_KEY` | JWKS does not contain the token `kid`. | Confirm the JWKS URL and key rotation state. | Do not debug these errors by disabling validation. The safer path is to decode the token payload, compare it with the gateway authorizer config, and verify the signing key or secret used by the identity provider. ## Most Common 401 Root Causes | Symptom | Likely cause | First action | | --------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------- | | `ERR_JWS_SIGNATURE_VERIFICATION_FAILED` | Wrong secret, wrong key, or token signed by a different issuer | Compare the gateway secret or key source with the actual issuer | | `ERR_JWT_CLAIM_VALIDATION_FAILED` | `iss` or `aud` mismatch | Decode the token and compare values exactly | | `ERR_JWT_EXPIRED` | Token expired | Refresh or mint a new token | | `AUTH_ERROR` | General verification failure | Inspect the token format, issuer, and config together | For a route-level walkthrough, see [JWT Common 401 Errors](/security/jwt-hs256-setup/jwt-common-401-errors.md) and [JWT Issuer and Audience Checks](/security/jwt-hs256-setup/jwt-issuer-and-audience-checks.md). ### Error Codes and Responses #### JOSEAlgNotAllowed An error returns when a JOSE Algorithm is not allowed per developer preference. Response ```json { "error": "Algorithm not allowed", "code": "ERR_JOSE_ALG_NOT_ALLOWED" } ``` #### JWEDecryptionFailed An error returns when a JWE ciphertext decryption fails. **Response** ```json { "error": "Decryption failed", "code": "ERR_JWE_DECRYPTION_FAILED" } ``` #### JWEInvalid An error returns when the JWE format is invalid. **Response** ```json { "error": "Invalid JWE", "code": "ERR_JWE_INVALID" } ``` #### JWTExpired An error returns when a JWT has expired. **Response** ```json { "error": "Token has expired.", "code": "ERR_JWT_EXPIRED" } ``` This means the token signature may be valid, but the token is no longer usable. Refresh the token or sign in again. #### JWTClaimValidationFailed An error returns when validation of a JWT claim fails. **Response** ```json { "error": "JWT claim validation failed", "code": "ERR_JWT_CLAIM_VALIDATION_FAILED" } ``` This often happens when staging and production use different `issuer` or `audience` values. Keep those values documented next to each environment's gateway config. #### JWTInvalid An error returns when the JWT is invalid. **Response** ```json { "error": "Invalid JWT", "code": "ERR_JWT_INVALID" } ``` #### JWKSNoMatchingKey An error returns when no matching key is found in the JWKS. **Response** ```json { "error": "No matching key found in JWKS.", "code": "ERR_JWKS_NO_MATCHING_KEY" } ``` #### JWKSInvalid An error returns when the JWKS is invalid. **Response** ```json { "error": "Invalid JWKS", "code": "ERR_JWKS_INVALID" } ``` #### JWKSMultipleMatchingKeys An error returns when multiple matching keys are found in the JWKS. **Response** ```json { "error": "Multiple matching keys found in JWKS.", "code": "ERR_JWKS_MULTIPLE_MATCHING_KEYS" } ``` #### JWSInvalid An error thrown when the JWS is invalid. **Response** ```json { "error": "Invalid JWS", "code": "ERR_JWS_INVALID" } ``` #### JWSSignatureVerificationFailed An error returns when JWS signature verification fails. **Response** ```json { "error": "Signature verification failed", "code": "ERR_JWS_SIGNATURE_VERIFICATION_FAILED" } ``` This is usually the query and error string people search for most. Check the signing secret first, then check whether the token came from the expected environment or identity provider. #### JWT Verification Failed An error thrown for any other JWT verification failures not specifically covered by the other errors. **Response** ```json { "error": "JWT verification failed", "code": "AUTH_ERROR" } ``` ### See Also * [Configuration Guide](/configuration/overview.md) -- full configuration reference including authorizer, CORS, and server settings. * [Paths](/configuration/paths.md) -- define which API endpoints require authentication using the `auth` flag. * [CORS](/configuration/cors.md) -- configure cross-origin settings that work alongside your authorization layer. * [Authentication Guide](/configuration/authentication.md) -- compare JWT, Auth0, and Supabase authentication flows. * [JWT Common 401 Errors](/security/jwt-hs256-setup/jwt-common-401-errors.md) -- troubleshoot common token verification failures. * [JWT Issuer and Audience Checks](/security/jwt-hs256-setup/jwt-issuer-and-audience-checks.md) -- debug claim mismatches safely. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.serverlessapigateway.com/configuration/authorizer.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.