OAuth and JWT Debugging Checklist

401, 403, bearer tokens, scopes, issuer, audience, expiration and refresh-token failures. Last updated August 31, 2026.

OAuth 2.0 defines access tokens as credentials used to access protected resources, and refresh tokens as credentials used to obtain new access tokens. See RFC 6749. JSON Web Token defines a compact claims format with registered claims such as iss, sub, aud, exp, nbf, iat and jti; see RFC 7519. This checklist turns those concepts into an API debugging workflow.

Separate 401 from 403

Status	Common meaning	Start here
401 Unauthorized	The request is missing valid authentication.	Token presence, token type, expiration, signature, issuer and audience.
403 Forbidden	The caller is authenticated but not allowed.	Scopes, roles, tenant boundary, resource ownership and policy rules.
419 or custom auth code	Session or CSRF-specific failure in some stacks.	Cookie settings, same-site policy, CSRF token and frontend origin.

Capture auth evidence with curl

curl -i https://api.example.com/me \
  -H "Authorization: Bearer REPLACE_WITH_TEST_TOKEN"

curl -i https://api.example.com/admin/reports \
  -H "Authorization: Bearer REPLACE_WITH_TEST_TOKEN" \
  -H "X-Request-Id: auth-debug-001"

JWT claim checklist

iss: the token issuer expected by the API.
sub: the user, client or service identity the API should authorize.
aud: the API audience; many 401 failures are audience mismatch issues.
exp: expiration time. Compare it with server time, not only laptop time.
nbf: not-before time; future tokens fail until this timestamp is reached.
scope or roles: permissions must match the operation, not merely the login.

Refresh-token failure path

grant_type=refresh_token
client_id checked:
client secret required:
refresh token rotated:
old refresh token revoked:
scope narrowed:
token endpoint status:
response error:

Incident note template

endpoint:
status:
auth scheme:
issuer:
audience:
subject type:
expires at:
server time:
scopes:
roles:
tenant:
resource owner:
failure layer:

Never paste live access tokens, refresh tokens or private signing keys into a public tool or support ticket. Decode only safe test tokens or redact sensitive values before sharing evidence.