API reference | AdonisJS JWT

Public factories, services, guard methods, contracts, errors, events, and commands.

Package entry point

`defineJwtConfig(config)`

Preserves driver-specific TypeScript inference while validating at provider boot. The config contains issuer, audience, access, refresh, keys, jwks, optional transport, and optional denylist fields.

`jwtGuard(options)`

Creates an Adonis auth guard factory. Required options are provider, keySet, config, and refreshStore. Optional options are transport, denylist, and a typed event emitter.

`keyDrivers`

keyDrivers.env({ privateKeyPem, publicKeyPem?, kid? })
keyDrivers.env({ privateKey, kid? }) for a private JWK
keyDrivers.env({ secret, kid? }) for HS256
keyDrivers.database({ table? })
keyDrivers.remoteJwks({ url, cacheMaxAge?, cooldownDuration?, timeoutDuration?, headers? })

Remote cache durations are milliseconds. JWT and JWKS response TTLs elsewhere are seconds or human-readable duration strings as indicated by their fields.

`transports`

transports.bearer() returns BearerTransport.
transports.cookie(options?) returns CookieTransport.

Cookie options: accessCookie, refreshCookie, csrfCookie, csrfHeader, accessPath, refreshPath, domain, sameSite, secure, and csrf.

Guard methods

Method	Result	Behavior
`authenticate()`	User	Verifies access token, denylist, and user lookup
`check()`	`boolean`	Authentication attempt without throwing
`getUserOrFail()`	User	Returns the previously authenticated user
`login(user)`	`IssuedTokens`	Issues access and refresh tokens; writes transport
`refresh(raw?)`	`IssuedTokens`	Consumes and rotates a refresh token
`logout(raw?)`	`void`	Revokes refresh, optionally denylists access, clears transport
`logoutAll(user)`	`void`	Revokes all refresh families for the user
`authenticateAsClient(user)`	`AuthClientResponse`	Supplies Japa API-client auth state

Validated access claims are available as ctx.jwtClaims.

Services and drivers

TokenService: issueAccess, issuePair, verifyAccess, rotateRefresh, revokeRefresh, revokeRefreshFamily, and revokeAllRefreshTokens.
KeySet: environment asymmetric keys.
HmacKeySet: HS256 secret with a 256-bit minimum.
DatabaseKeySet: encrypted shared keys and strict-TTL rotation.
RemoteJwksKeySet: cached external verification keys; no signing or rotation.
RefreshTokenStore: opaque token creation, lookup, consumption, family revocation, and user revocation.
MemoryDenylist and CacheDenylist: optional access-token jti revocation.
JwksController: public JWKS response and cache header.

The ./providers export supplies lucidJwtUserProvider({ model }).

Token shapes

IssuedTokens contains:

interface IssuedTokens {
  tokenType: 'bearer'
  accessToken: string
  expiresIn: number
  refreshToken: string
  refreshExpiresIn: number
}

AccessTokenClaims contains strict iss, aud, sub, jti, type: 'access', iat, nbf, and exp, plus optional scope and roles.

Exceptions

Import exception constructors through errors from the package root. Stable codes:

E_TOKEN_EXPIRED — 401
E_TOKEN_REVOKED — 401
E_INVALID_REFRESH_TOKEN — 401
E_REFRESH_TOKEN_REUSE — 401
E_CSRF_TOKEN_MISMATCH — 403
E_JWT_CONFIG — 500

Each renders { errors: [{ code, message }] }.

Events

JwtEvents and JwtEmitter type the events jwt:login, jwt:authenticated, jwt:authentication_failed, jwt:refreshed, jwt:refresh_reuse_detected, jwt:logout, and jwt:key_rotated.

Ace commands

node ace jwt:make-key
node ace jwt:rotate-keys

The first prints an Ed25519 environment key pair. The second requires the database key driver and performs introduce, promote, and strict-TTL retirement.