nbf (Not Before) Claim
The nbf (not before) claim is a registered NumericDate before which the JWT must not be accepted. It enables scheduled token activation — for example, access that opens at midnight or after provisioning completes. Verifiers compare current time against nbf, often with a small clock skew leeway. Tokens with nbf in the future should return unauthorized until the window opens. Implementations across Node.js, Python, Go, Ruby, and Java follow the same RFC standards, so concepts transfer directly between stacks. Security reviews should treat this as part of your full authentication threat model, not an isolated configuration detail. Document expected behavior for client teams so tokens are issued, stored, and validated consistently across services.
Why It Matters
nbf is useful for pre-issued credentials, maintenance windows, and phased rollouts. Without nbf validation, pre-generated tokens might be used earlier than intended. Document skew tolerance consistently across microservices to avoid flaky authorization. Getting this wrong often surfaces only after an incident, when forged or replayed tokens expose gaps in validation or secret handling. Platform teams should encode these rules in libraries, linting, and deployment checklists so individual services cannot drift silently. Pair technical controls with monitoring: log verification failures, track unusual token lifetimes, and alert on spikes in 401 responses. Review this during every auth-related change, including framework upgrades, CDN additions, and new mobile or third-party clients.
Code Example
{
"sub": "user_42",
"nbf": 1720454400,
"exp": 1720458000
}Related Terms
Related Tools
Related Articles
Frequently Asked Questions
Is nbf commonly used?
Less common than exp, but valuable for scheduled access and pre-provisioned tokens. Consult your JWT library documentation for exact option names, defaults, and error types. When in doubt, prefer stricter validation and shorter token lifetimes over permissive shortcuts. Test edge cases with expired, malformed, and wrong-algorithm tokens in CI before shipping auth changes.
What if nbf is after exp?
The token is invalid — no valid time window exists. Reject during validation. Consult your JWT library documentation for exact option names, defaults, and error types. When in doubt, prefer stricter validation and shorter token lifetimes over permissive shortcuts. Test edge cases with expired, malformed, and wrong-algorithm tokens in CI before shipping auth changes.
Clock skew with nbf?
Allow a small leeway (30–60s) so minor clock drift does not cause false rejections. Consult your JWT library documentation for exact option names, defaults, and error types. When in doubt, prefer stricter validation and shorter token lifetimes over permissive shortcuts.