Authentication

JWT Authentication

Sign and verify JSON Web Tokens with AxilJS using HS256/HS384/HS512, expiry, audience and issuer claims, and constant-time signature checks.

3 min readUpdated DocumentationEdit this page
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.

TypeScript
TS
1import { JWT } from '@axiljs/auth'
2
3const jwt = new JWT(
4  process.env.JWT_SECRET
5) // min 32 chars

The 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

TypeScript
TS
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.

TypeScript
TS
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.

TypeScript
TS
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

TypeScript
TS
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

TypeScript
TS
const claims = jwt.decode(token) // JWTPayload | null, signature NOT checked

Applications 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:

Output
TXT
45s
30m
1h
7d
2w

The accepted units are s, m, h, d and w. You can also provide the expiration as a number representing seconds.

For example:

TypeScript
TS
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?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY