Cookies and token transport
The access token and the refresh token can travel in the Authorization header, in cookies, or in the request body for the refresh token.
Which transport to pick
- Browsers: use cookies. They are
HttpOnly, so JavaScript can't read them. Don't return the tokens in the response body as well, see Single-page apps. - Mobile apps, CLIs, other services: send the access token in the
Authorizationheader, and the refresh token in the request body or theAuthorizationheader.
Access token
By default, the guard reads the access token from the Authorization: Bearer <token> header. Set useCookies to also accept it from a cookie:
jwtGuard({
// ...
useCookies: true,
tokenName: 'token', // name of the cookie, 'token' by default
})With useCookies, generate() sets the access token cookie on the response, with a Max-Age matching tokenExpiresIn.
The guard reads the access token from, in order:
- the
Authorization: Bearer <token>header; - the cookie named after
tokenName, only whenuseCookiesis enabled.
The header comes first because the client sets it explicitly, while the browser sends cookies on every request: a stale cookie never shadows a valid bearer token.
Refresh token
Set useCookiesForRefreshToken to send the refresh token as a cookie:
jwtGuard({
// ...
useCookiesForRefreshToken: true,
refreshTokenName: 'refreshToken', // name of the cookie and of the body field
})The guard reads the refresh token from, in order:
- the cookie named after
refreshTokenName, whenuseCookiesForRefreshTokenis enabled; - the request body field named after
refreshTokenName. This is how OAuth 2.0 transmits refresh tokens (RFC 6749 §6); - the
Authorization: Bearer <token>header.
A refresh token passed in the query string is ignored, since URLs end up in access logs, browser history and Referer headers.
useCookies and useCookiesForRefreshToken are independent: you can, for example, keep the access token in memory and send it in the header, while the refresh token lives in a cookie.
Cookie options
Cookies set by the guard are HttpOnly and Secure by default. Override these defaults or set other options with cookie:
jwtGuard({
// ...
cookie: {
httpOnly: true, // default
secure: true, // default
sameSite: 'strict',
path: '/',
},
})maxAge and expires can't be set: the guard derives them from tokenExpiresIn and refreshTokenExpiresIn. The same options apply to both cookies.
Options that you don't set come from http.cookie in config/app.ts (sameSite: 'lax' and path: '/' in new apps). The cookies are signed with the application key, not encrypted: they can't be forged, and they are HttpOnly, but the JWT inside is readable by anyone who gets the cookie, like any JWT.
Use secure: app.inProduction if you develop over plain HTTP on another hostname than localhost.
CSRF
Browsers send cookies automatically, including on requests triggered by other sites. When you authenticate with cookies, protect the routes that change data:
sameSite: 'lax'or'strict'stops other sites from sending the cookies with theirPOSTrequests.laxstill sends them on top-levelGETnavigations, soGETroutes must not change data.SameSiteworks per site, not per origin: another subdomain of your domain, for example one that hosts user content, is the same site.- The CSRF protection of
@adonisjs/shield(with@adonisjs/session) adds a token check. Inertia forms send the token automatically. A SPA reads theXSRF-TOKENcookie and sends it back in theX-XSRF-TOKENheader (axios does it by default, see Single-page apps forfetch()). By default, Shield answers an invalid token with a redirect back, not a403: handleE_BAD_CSRF_TOKENin your exception handler if your API clients need a status code.
The CSRF protection applies to every POST route, including those used by mobile apps or other services that send the token in the Authorization header and have no CSRF token. Exclude them with exceptRoutes, and authenticate them with a second JWT guard without cookies, so that a cookie can't authenticate a request on a route that Shield no longer protects.
Logging
Make sure your logging middleware doesn't record request bodies, cookies or Authorization headers on authentication routes, otherwise tokens end up in plain text in your logs.