JWT Authentication
Sign and verify JSON Web Tokens with AxilJS using HS256/HS384/HS512, expiry, audience and issuer claims, and constant-time signature checks.
On this page8
AxilJS provides a JWT utility for signing and verifying JSON Web Tokens using HMAC-SHA256 by default (HS384 and HS512 are also supported).
JWTs can be used to represent authenticated user information and securely transfer claims between your application components.
Setup
Import JWT from @axiljs/auth and initialize it with a secret.
1import { JWT } from '@axiljs/auth'
2
3const jwt = new JWT(
4 process.env.JWT_SECRET
5) // min 32 charsThe JWT secret must be at least 32 characters long; the constructor throws otherwise. Store the secret securely in an environment variable rather than directly in application source code.
Algorithm
const jwt = new JWT(process.env.JWT_SECRET, { algorithm: 'HS512' }) // 'HS256' (default) | 'HS384' | 'HS512'verify() only accepts tokens whose header uses the configured algorithm.
Sign a Token
Use jwt.sign() to create a signed JWT containing application claims.
1const token = jwt.sign(
2 {
3 sub: String(user.id),
4 role: 'admin'
5 },
6 {
7 expiresIn: '7d'
8 }
9)The payload in this example contains:
sub— the subject identifier, representing the user ID.role— an application-specific authorization claim.expiresIn— controls how long the generated token remains valid.
The resulting token can be returned to an authenticated client and subsequently presented when accessing protected resources.
Verify a Token
Use jwt.verify() to verify a token and retrieve its payload.
const payload = jwt.verify(token)Verification validates the signature, algorithm, exp and nbf, and returns the decoded payload. Any failure throws an UnauthorizedError (for example Token has expired or Invalid token signature).
Audience and issuer
1const token = jwt.sign(
2 { sub: String(user.id) },
3 { expiresIn: '15m', audience: 'api', issuer: 'auth.example.com' }
4)
5
6jwt.verify(token, { audience: 'api', issuer: 'auth.example.com' })sign() also accepts notBefore (same format as expiresIn). audience may be a string or an array of strings in both sign() and verify().
Decode without verifying
const claims = jwt.decode(token) // JWTPayload | null, signature NOT checkedApplications should perform JWT verification before trusting claims such as user identifiers or roles.
Token Expiration
AxilJS supports human-readable expiration formats as well as numeric seconds.
Supported examples include:
45s
30m
1h
7d
2wThe accepted units are s, m, h, d and w. You can also provide the expiration as a number representing seconds.
For example:
1const token = jwt.sign(
2 { sub: String(user.id) },
3 { expiresIn: '1h' }
4)Shorter expiration periods can be useful for tokens that should have a limited lifetime.
JWT Security
JWT signature verification uses constant-time comparison to reduce the risk of timing attacks.
Warning
Signature comparison uses constant-time comparison to prevent timing attacks.
Keep the JWT secret private and use a sufficiently strong secret in production. Never expose the signing secret to browser-side code or commit it to source control.
Was this page helpful?