Stay organized with collections
Save and categorize content based on your preferences.
When a client application includes a JSON Web Token (JWT) in a request to an
API, the Extensible Service Proxy (ESP)
validates the JWT before sending the request to the API
backend. This page provides troubleshooting information if the JWT validation
fails and ESP returns an error in the response to the client. See
RFC 7519 for more information
about JWTs.
Error: 401: Jwt issuer is not configured
This may happen when deploying ESPv2 in Cloud Run, the flag
--allow-unauthenticated is not used in gcloud run deploy command.
If the flag is not used, the JWT token is intercepted
and verified by Cloud Run access
control IAM server and not by ESPv2. IAM may use a different issuer than
ESPv2.
Error: BAD_FORMAT
Check the
following:
Make sure the JWT contains valid JSON.
Check that the JWT header has the "alg" field and is set to one of the
following: "RS256", "HS256", "RS384",
"HS384", "RS512", or "HS512"
Check the data type of the following fields (if they are present) in the
JWT payload:
The "iat" (issued at), "exp" (expiration time), and
"nbf"(not before) claims are numbers greater than 0 and not
strings.
The "sub" (subject), "iss" (issuer), and
"jti" (JWT ID) fields
are strings.
The "aud" (audience) claim is either a string or an array of
strings.
Ensure that the following claims are present in the JWT payload:
"sub" (subject), "iss" (issuer), and
"aud" (audience).
The following is an example of a decoded JWT token that is valid:
The "exp" (expiration time) claim value is a date and time in the
future. The current date and time must be before the expiration date and time listed
in the "exp" claim.
The "nbf" (not before) claim (If present) is a date and time in the
past. The current date and time must be after or equal to the date and time listed in
the "nbf" claim.
If the "iss" (issuer) claim is an email address, then the "sub" (subject)
and "iss" claims should be the same.
This is to ensure that for e-mail issuers, the JWT is self issued.
Error: KEY_RETRIEVAL_ERROR
Check that the public key URI specified in the second parameter of the
endpoints.Issuer
object is correct and valid.
Error: Issuer not allowed
Check that the "iss" (issuer) claim in your JWT token matches the
first parameter of the
endpoints.Issuer
object.
Error: Audience not allowed
If the "aud" (audience) claim in a JWT token matches the
Endpoints service name, then Cloud Endpoints Frameworks validates
the audience and ignores the values set in the
audiences
argument in the @endpoints.api decorator. For example, if your service name
is "myservice.appspot.com", then a JWT with "aud" set to
"myservice.appspot.com" or "https://myservice.appspot.com" is a valid
audience.
If the "aud" claim is not the same as the Endpoints service
name:
Check that the "aud" claim in the JWT matches one of the values in the
audiences argument in the @endpoints.api decorator.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[[["\u003cp\u003eThe Extensible Service Proxy (ESP) validates JSON Web Tokens (JWTs) before allowing requests to reach the API backend, and this page provides troubleshooting for validation failures.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003e401: Jwt issuer is not configured\u003c/code\u003e error may occur in Cloud Run deployments if the \u003ccode\u003e--allow-unauthenticated\u003c/code\u003e flag is omitted during the \u003ccode\u003egcloud run deploy\u003c/code\u003e command.\u003c/p\u003e\n"],["\u003cp\u003eA \u003ccode\u003eBAD_FORMAT\u003c/code\u003e error indicates issues with the JWT's structure or content, such as invalid JSON, incorrect \u003ccode\u003e"alg"\u003c/code\u003e field values, or improper data types within claims like \u003ccode\u003e"iat"\u003c/code\u003e, \u003ccode\u003e"exp"\u003c/code\u003e, \u003ccode\u003e"nbf"\u003c/code\u003e, \u003ccode\u003e"sub"\u003c/code\u003e, \u003ccode\u003e"iss"\u003c/code\u003e, \u003ccode\u003e"jti"\u003c/code\u003e, and \u003ccode\u003e"aud"\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eTIME_CONSTRAINT_FAILURE\u003c/code\u003e errors mean the JWT's \u003ccode\u003e"exp"\u003c/code\u003e (expiration time) or \u003ccode\u003e"nbf"\u003c/code\u003e (not before) claims are not valid, requiring verification using tools like jwt.io to ensure time constraints are met.\u003c/p\u003e\n"],["\u003cp\u003eWhen encountering \u003ccode\u003eUNKNOWN\u003c/code\u003e, \u003ccode\u003eKEY_RETRIEVAL_ERROR\u003c/code\u003e, \u003ccode\u003eIssuer not allowed\u003c/code\u003e, or \u003ccode\u003eAudience not allowed\u003c/code\u003e errors, carefully verify the JWT claims, public key URI, and alignment with the \u003ccode\u003eendpoints.Issuer\u003c/code\u003e object and \u003ccode\u003e@endpoints.api\u003c/code\u003e decorator settings.\u003c/p\u003e\n"]]],[],null,["# Troubleshooting JWT validation\n\nWhen a client application includes a JSON Web Token (JWT) in a request to an\nAPI, the [Extensible Service Proxy (ESP)](/endpoints/docs/openapi/glossary#extensible_service_proxy)\nvalidates the JWT before sending the request to the API\nbackend. This page provides troubleshooting information if the JWT validation\nfails and ESP returns an error in the response to the client. See\n[RFC 7519](https://tools.ietf.org/html/rfc7519) for more information\nabout JWTs.\n**Error: `401: Jwt issuer is not configured`**\n\nThis may happen when deploying ESPv2 in Cloud Run, the flag\n`--allow-unauthenticated` is not used in `gcloud run deploy` command.\nIf the flag is not used, the JWT token is intercepted\nand verified by Cloud Run access control IAM server and not by ESPv2. IAM may use a different issuer than ESPv2.\n**Error: `BAD_FORMAT`**\n\nCheck the\nfollowing:\n\n- Make sure the JWT contains valid JSON.\n- Check that the JWT header has the `\"alg\"` field and is set to one of the following: `\"RS256\"`, `\"HS256\"`, `\"RS384\"`, `\"HS384\"`, `\"RS512\"`, or `\"HS512\"`\n- Check the data type of the following fields (if they are present) in the JWT payload:\n - The `\"iat\"` (issued at), `\"exp\"` (expiration time), and `\"nbf\"`(not before) claims are numbers greater than 0 and not strings.\n - The `\"sub\"` (subject), `\"iss\"` (issuer), and `\"jti\"` (JWT ID) fields are strings.\n - The `\"aud\"` (audience) claim is either a string or an array of strings.\n- Ensure that the following claims are present in the JWT payload: `\"sub\"` (subject), `\"iss\"` (issuer), and `\"aud\"` (audience).\n\nThe following is an example of a decoded JWT token that is valid: \n\n```\n{\n \"alg\": \"RS256\",\n \"typ\": \"JWT\",\n \"kid\": \"42ba1e234ac91ffca687a5b5b3d0ca2d7ce0fc0a\"\n}\n\nPayload:\n{\n \"iss\": \"myservice@myproject.iam.gserviceaccount.com\",\n \"iat\": 1493833746,\n \"aud\": \"myservice.appspot.com\",\n \"exp\": 1493837346,\n \"sub\": \"myservice@myproject.iam.gserviceaccount.com\"\n}\n```\n**Error: `TIME_CONSTRAINT_FAILURE`**\n\nUse [jwt.io](https://jwt.io/) to decode the JWT and make sure that:\n\n- The `\"exp\"` (expiration time) claim exists.\n- The `\"exp\"` (expiration time) claim value is a date and time in the future. The current date and time must be before the expiration date and time listed in the `\"exp\"` claim.\n- The `\"nbf\"` (not before) claim (If present) is a date and time in the past. The current date and time must be after or equal to the date and time listed in the `\"nbf\"` claim.\n\n**Error: `UNKNOWN`**\n\nUse [jwt.io](https://jwt.io/) to decode the JWT and ensure that:\n\n- If the `\"iss\"` (issuer) claim is an email address, then the `\"sub\"` (subject) and `\"iss\"` claims should be the same. This is to ensure that for e-mail issuers, the JWT is self issued.\n\n**Error: `KEY_RETRIEVAL_ERROR`**\n\n- Check that the public key URI specified in the second parameter of the [`endpoints.Issuer`](/endpoints/docs/frameworks/python/decorators-reference#defining_the_api_endpointsapi) object is correct and valid.\n\n**Error: `Issuer not allowed`**\n\n- Check that the `\"iss\"` (issuer) claim in your JWT token matches the first parameter of the [`endpoints.Issuer`](/endpoints/docs/frameworks/python/decorators-reference#defining_the_api_endpointsapi) object.\n\n**Error: `Audience not allowed`**\n\nIf the `\"aud\"` (audience) claim in a JWT token matches the\nEndpoints service name, then Cloud Endpoints Frameworks validates\nthe audience and ignores the values set in the\n[`audiences`](/endpoints/docs/frameworks/python/decorators-reference#defining_the_api_endpointsapi)\nargument in the `@endpoints.api` decorator. For example, if your service name\nis `\"myservice.appspot.com\"`, then a JWT with `\"aud\"` set to\n`\"myservice.appspot.com\"` or `\"https://myservice.appspot.com\"` is a valid\naudience.\n\nIf the `\"aud\"` claim is not the same as the Endpoints service\nname:\n\n- Check that the `\"aud\"` claim in the JWT matches one of the values in the `audiences` argument in the `@endpoints.api` decorator."]]