Installation | AdonisJS JWT

Install and configure

From an AdonisJS v7 application:

node ace add @rikology/adonisjs-jwt

The configure hook creates config/jwt.ts, an auth controller, refresh-token and signing-key migrations, then registers the service provider and Ace commands in adonisrc.ts. It also adds JWT variables and validation to your environment files.

Generate an Ed25519 key pair

node ace jwt:make-key

Copy both printed assignments to .env. The values are JSON-quoted so embedded newlines are safe. Never reuse APP_KEY as a JWT key and never commit the private key.

JWT_ISSUER=https://api.example.com
JWT_AUDIENCE=example-app
JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
JWT_KID=2026-08-primary

JWT_ISSUER identifies the service that creates tokens. JWT_AUDIENCE identifies the intended consumer. Both are mandatory verification constraints, not descriptive metadata. JWT_KID should identify the deployed key version and must change when an environment key is replaced.

Create the tables

node ace migration:run

The refresh table stores only SHA-256 token hashes, lifecycle timestamps, and family lineage. The signing-key table is used only when you opt into the encrypted database key driver.

Register the guard

Complete the exact config/auth.ts setup, then start the application. Invalid durations, missing keys, short HS256 secrets, and malformed remote-JWKS URLs fail during boot rather than during the first request.