2026-09-11 · 6 min read · Rahul Chitturi
- jwt
- oauth
- authorization
One issuer may serialize scope as the OAuth-style string "orders:read orders:write", while another token profile uses an array or a differently named claim such as scp. Code that assumes the wrong shape can deny valid requests or, more dangerously, grant permission after an unsafe substring match.
Decoding the token reveals the claim representation but does not establish signature validity, issuer trust, audience, or authorization.
Name the accepted token profile
For each trusted issuer and token type, document the claim name, JSON type, delimiter rules, case sensitivity, allowed vocabulary, and behavior for duplicate or unknown entries. Reject types outside that profile rather than coercing arbitrary values.
- Split a defined scope string on the specified space character.
- Compare complete permission values, never substrings.
- Do not merge scope and role semantics implicitly.
- Apply issuer and audience checks before using claims.
Keep gateway and service decisions aligned
A gateway and downstream service must interpret the same validated token profile. If a gateway translates claims into headers, authenticate that internal hop, overwrite client-supplied copies, and preserve enough provenance to audit the decision.
Return a clear distinction between missing or invalid authentication and an authenticated principal lacking permission, without exposing sensitive token details.
Test synthetic claim shapes
Use the JWT decoder with disposable signed or unsigned fixtures, JSON formatter to expose string and array types, diff for policy changes, and case converter for documented naming checks. Never paste live access tokens into debugging tools.
Cover missing, null, string, array, duplicate, empty, mixed-case, prefix-collision, Unicode-whitespace, unknown-scope, multi-issuer, expired, wrong-audience, and gateway-forwarding cases.