---
title: "API reference"
description: "Public factories, services, guard methods, contracts, errors, events, and commands."
image: "https://adonisjs-jwt.pages.dev/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://adonisjs-jwt.pages.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

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

```ts
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

```sh
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.

Source: https://adonisjs-jwt.pages.dev/api/index.mdx