Authorizer

Configure JWT authorization with HS256 for the Serverless API Gateway. Includes JOSE JWT error codes, claim validation failures, and fixes for common 401 token errors.

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.

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 and error states implemented with its error types. Example response:

{
    "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 and JWT Issuer and Audience Checks.

Error Codes and Responses

JOSEAlgNotAllowed

An error returns when a JOSE Algorithm is not allowed per developer preference.

Response

{
    "error": "Algorithm not allowed",
    "code": "ERR_JOSE_ALG_NOT_ALLOWED"
}

JWEDecryptionFailed

An error returns when a JWE ciphertext decryption fails.

Response

{
    "error": "Decryption failed",
    "code": "ERR_JWE_DECRYPTION_FAILED"
}

JWEInvalid

An error returns when the JWE format is invalid.

Response

{
    "error": "Invalid JWE",
    "code": "ERR_JWE_INVALID"
}

JWTExpired

An error returns when a JWT has expired.

Response

{
    "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

{
    "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

{
    "error": "Invalid JWT",
    "code": "ERR_JWT_INVALID"
}

JWKSNoMatchingKey

An error returns when no matching key is found in the JWKS.

Response

{
    "error": "No matching key found in JWKS.",
    "code": "ERR_JWKS_NO_MATCHING_KEY"
}

JWKSInvalid

An error returns when the JWKS is invalid.

Response

{
    "error": "Invalid JWKS",
    "code": "ERR_JWKS_INVALID"
}

JWKSMultipleMatchingKeys

An error returns when multiple matching keys are found in the JWKS.

Response

{
    "error": "Multiple matching keys found in JWKS.",
    "code": "ERR_JWKS_MULTIPLE_MATCHING_KEYS"
}

JWSInvalid

An error thrown when the JWS is invalid.

Response

{
    "error": "Invalid JWS",
    "code": "ERR_JWS_INVALID"
}

JWSSignatureVerificationFailed

An error returns when JWS signature verification fails.

Response

{
    "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

{
    "error": "JWT verification failed",
    "code": "AUTH_ERROR"
}

See Also

• Configuration Guide -- full configuration reference including authorizer, CORS, and server settings.

• Paths -- define which API endpoints require authentication using the auth flag.

• CORS -- configure cross-origin settings that work alongside your authorization layer.

• Authentication Guide -- compare JWT, Auth0, and Supabase authentication flows.

• JWT Common 401 Errors -- troubleshoot common token verification failures.

• JWT Issuer and Audience Checks -- debug claim mismatches safely.