# AdonisJS JWT > JWT authentication package for AdonisJS v7: an auth guard with access tokens, rotating refresh tokens, HttpOnly cookies, RSA/ECDSA keys and JWKS verification. `@maximemrf/adonisjs-jwt` is the JWT authentication guard for AdonisJS. It plugs into the official `@adonisjs/auth` package, so routes are protected with the regular `auth` middleware and the user is read with `auth.getUserOrFail()`. There is no need to write a custom middleware around `jsonwebtoken` or `jose`. Key facts: - Current version: 1.x, for AdonisJS v7 and Node.js >= 24. AdonisJS v6 apps use `0.7.1`, the last version that supports v6. - Install with `node ace add @maximemrf/adonisjs-jwt`. It installs the package, adds a `jwt` guard to `config/auth.ts` and, if asked, creates the refresh tokens migration. - Import from the main entrypoint: `import { jwtGuard } from '@maximemrf/adonisjs-jwt'`. The `@maximemrf/adonisjs-jwt/jwt_config` path from 0.x still works but is no longer the documented one. - Access tokens are signed with HMAC by default, with a key derived from `APP_KEY` (no secret to manage), and expire after 1 hour (`tokenExpiresIn`). A `secret` must be at least 32 characters. - Issue a token with `auth.use('jwt').generate(user)`, or an access token and a refresh token with `auth.use('jwt').generateWithRefreshToken(user)`. - Refresh tokens are stored in the database, rotated on each use, protected against replay, and expire after 7 days by default (`refreshTokenExpiresIn`). - Tokens can be sent in the `Authorization: Bearer` header or in HttpOnly cookies, for SPAs and Inertia apps. - Asymmetric signing (RS256, ES256) and JWKS verification of tokens issued by an identity provider (Auth0, Keycloak, FerrisKey, Kubernetes ServiceAccount tokens). - The configuration is validated when the app boots, so a short secret or a bad key fails at startup. - Japa's `loginAs` works with the API client. When to use it: a mobile app, a SPA on another domain or another service authenticates against an AdonisJS API, or the API verifies tokens from an identity provider. When the frontend and the API share a domain, the built-in session guard is usually simpler. For long-lived API tokens revoked one by one, the built-in access tokens guard (opaque tokens) fits better. Minimal `config/auth.ts`: ```ts import { defineConfig } from '@adonisjs/auth' import { sessionUserProvider } from '@adonisjs/auth/session' import { jwtGuard } from '@maximemrf/adonisjs-jwt' export default defineConfig({ default: 'jwt', guards: { jwt: jwtGuard({ provider: sessionUserProvider({ model: () => import('#models/user') }), }), }, }) ``` Links: [npm](https://www.npmjs.com/package/@maximemrf/adonisjs-jwt), [GitHub](https://github.com/MaximeMRF/adonisjs-jwt), [starter app](https://github.com/MaximeMRF/adonisjs-jwt-starter), [Kubernetes example](https://github.com/MaximeMRF/adonisjs-jwt-k8s-example). The whole documentation in one file: [llms-full.txt](https://maximemrf.github.io/adonisjs-jwt/llms-full.txt). ## Table of Contents ### Getting started - [Introduction](https://maximemrf.github.io/adonisjs-jwt/guide/introduction.md): What the AdonisJS JWT guard does, how it fits into @adonisjs/auth, and when to use JWT access tokens instead of sessions or opaque tokens. - [Installation](https://maximemrf.github.io/adonisjs-jwt/guide/installation.md): Install @maximemrf/adonisjs-jwt in an AdonisJS v7 app and configure the JWT guard and the refresh tokens table with node ace configure. - [Configuration](https://maximemrf.github.io/adonisjs-jwt/guide/configuration.md): Configure the AdonisJS JWT guard: token lifetime, payload, signing key, issuer and audience, next to the session guard. - [Authentication](https://maximemrf.github.io/adonisjs-jwt/guide/authentication.md): Log users in with JWT in AdonisJS: issue access tokens, protect routes with the auth middleware and read the authenticated user. ### Guides - [Refresh tokens](https://maximemrf.github.io/adonisjs-jwt/guide/refresh-tokens.md): Rotating refresh tokens for AdonisJS JWT: database table, refresh endpoint, abilities, revocation on logout and several JWT guards. - [Cookies and token transport](https://maximemrf.github.io/adonisjs-jwt/guide/token-transport.md): Send AdonisJS JWT tokens in the Authorization header or in HttpOnly cookies, with SameSite, CSRF protection and cookie options. - [Single-page apps](https://maximemrf.github.io/adonisjs-jwt/guide/spa.md): Use AdonisJS JWT with a single-page app: cookies across subdomains, CORS with credentials, and a fetch wrapper that refreshes once. - [Inertia and server-rendered apps](https://maximemrf.github.io/adonisjs-jwt/guide/inertia.md): Use AdonisJS JWT with Inertia and server-rendered apps: cookie tokens, login and logout controllers, and redirects to the login page. - [Asymmetric signing](https://maximemrf.github.io/adonisjs-jwt/guide/asymmetric.md): Sign AdonisJS JWT access tokens with RSA or ECDSA keys (RS256, ES256) so other services can verify them with the public key. - [JWKS](https://maximemrf.github.io/adonisjs-jwt/guide/jwks.md): Verify tokens from an identity provider in AdonisJS with JWKS: issuer, audience, allowed algorithms, key caching and rotation. - [FerrisKey](https://maximemrf.github.io/adonisjs-jwt/guide/ferriskey.md): Authenticate an AdonisJS API with FerrisKey tokens through JWKS: client, audience mapper, guard configuration and client_credentials. - [Kubernetes ServiceAccount tokens](https://maximemrf.github.io/adonisjs-jwt/guide/kubernetes.md): Authenticate services in Kubernetes with ServiceAccount tokens verified by an AdonisJS API in JWKS mode, without any shared secret. - [Testing](https://maximemrf.github.io/adonisjs-jwt/guide/testing.md): Test AdonisJS routes protected by the JWT guard with Japa: loginAs with the API client, and the session guard alongside. - [Security](https://maximemrf.github.io/adonisjs-jwt/guide/security.md): Security model of the AdonisJS JWT guard: signing key derivation, secret strength, stateless access tokens and refresh token replay. ### Reference - [Options](https://maximemrf.github.io/adonisjs-jwt/reference/options.md): Every option of the AdonisJS JWT guard: secret, keys, JWKS, lifetimes, cookies, refresh tokens, content, getUserId and verifyPayload. - [Guard API](https://maximemrf.github.io/adonisjs-jwt/reference/guard.md): API reference of the AdonisJS JWT guard: generate, authenticate, check, generateWithRefreshToken, revoke and the user provider contract. ### Upgrading - [Upgrading to 1.0](https://maximemrf.github.io/adonisjs-jwt/upgrading/1.0.md): Upgrade @maximemrf/adonisjs-jwt from 0.x to 1.0: breaking changes, new defaults and the steps to migrate an AdonisJS app.