{
"sub": "usr_01HXYZ92KBWQ4", // who the token is about
"iss": "https://auth.example.com", // who issued it
"aud": "api.example.com", // intended recipient
"exp": 1893456000, // expires at (Unix)
"iat": 1893452400, // issued at (Unix)
"nbf": 1893452400, // not before
"https://example.com/roles": ["admin"] // custom claim
}
// xclaim! — validate every field, trust nothing by defaultThe Claims Object: Heart of Every JWT
A JSON Web Token is three Base64URL-encoded segments separated by dots: a header, a payload, and a signature. The payload is the claims object — a JSON document asserting facts about the principal represented by the token. Getting these claims right, and validating them correctly on every request, is the difference between a secure system and one that is vulnerable to token forgery, replay attacks, and privilege escalation. xClaim — xclaim! — makes this feel effortless.
Registered Claims: The Foundation
The JWT specification (RFC 7519) defines seven registered claim names. These are not required, but when present they have precise, standard meanings that every JWT library understands.
The sub (subject) claim identifies the principal the token represents — typically a user ID, service account identifier, or device ID. It should be unique within the issuer's namespace and stable across token refreshes for the same principal.
The iss (issuer) claim identifies the authorization server that issued the token. Validating this claim prevents tokens from one system from being accepted by another. Your validation logic must check that the issuer matches an expected value before trusting any other claim in the token.
The aud (audience) claim specifies the intended recipients of the token. A token issued for your API should not be accepted by a different service, even if both trust the same issuer. The aud claim is your defense against confused deputy attacks. Validate it precisely and reject tokens with an unexpected audience.
The exp (expiration time) and iat (issued at) claims bound the token's validity window. Always validate exp against the current time. Allow a small clock skew tolerance (typically 30-60 seconds) to handle slight time differences between issuer and validator. The nbf (not before) claim prevents a token from being used before its validity period begins, useful for scheduled access grants.
Custom Claims: Extending the Payload
Beyond registered claims, JWT payloads commonly carry application-specific assertions: roles, permissions, tenant identifiers, subscription tiers, email addresses, and feature flags. These custom claims are where identity meets authorization. xClaim's claim enrichment pipeline lets you inject custom claims at token issuance time and validate their presence and values at enforcement points throughout your application.
Custom claim names should use namespaced URIs or a vendor prefix to avoid collisions with registered claims and with claims added by other systems in your stack. A claim named roles is ambiguous; a claim named https://yourcompany.com/roles is not.
The Xclaim! Moment
There is a particular satisfaction in watching a correctly structured JWT flow through a validation pipeline and emerge with all claims verified, the signature confirmed against the issuer's JWKS, and the resulting identity ready to drive authorization decisions. xClaim is built to make that moment reliable, repeatable, and fast enough that it adds no perceptible latency to your request path. Secure authentication should feel like a superpower, not a burden — xclaim!
Claim Validation in Practice
xClaim's validation engine lets you declare claim requirements as composable rules. Require that the iss matches one of a set of trusted issuers. Require that the aud contains your service identifier. Require that a custom roles claim contains at least one of a set of allowed values. Chain rules together with boolean logic. Test the entire ruleset against a sample token in your test suite. Deploy with confidence that the same rules apply in every environment.