JWT Debugging Workflow

When an API returns 401 Unauthorized or 403 Forbidden, decoding the JWT can narrow the problem quickly.

Start with the shape

Confirm the token has three segments and is not truncated by a copy, proxy, header limit, or line wrap.

Inspect time claims

Check exp, nbf, and iat.

• If exp is in the past, request a new token.
• If nbf is in the future, look for clock skew or wrong environment time.
• If iat is surprising, confirm the client is using the expected issuer.

Check issuer and audience

Compare iss and aud with the API you are calling. A common OAuth bug is using an ID token where an access token is required.

Check scopes and roles

If authentication succeeds but authorization fails, inspect scope, scp, roles, permissions, or your provider's equivalent fields.

Verify in the real system

After decoding points you in the right direction, reproduce the request through the actual backend verifier. A decoder explains the token; the verifier decides whether it is accepted.