content/guides/03.auth/1.tokens-cookies.md
Access tokens are used to authenticate requests to Directus. They are scoped to users, and have the same permissions that the associated user does.
Standard tokens are returned when a user logs in and expire after a short period, and are provided with an expiry time as well as a refresh token.
Refresh tokens have a much longer expiry time, and can be used to generate a new standard token.
The token should be stored and reused by your application, checking if it has expired before each use and refreshing if required. Logging out will invalidate the refresh token, stopping a user from authenticating without first logging in again.
::callout{icon="material-symbols:menu-book-outline" color="primary" to="/guides/auth/email-login"} Read more about logging in, refreshing tokens, and logging out. ::
Session tokens are returned when a user logs in, and combine both an access and refresh token in a single token. They can only be refreshed before they expire, and must be stored as a cookie.
Each user can have one static token that does not expire. This can be generated in the Data Studio within the user page. It is stored in plain text in the directus_users collection, and can be manually set via the Data Studio or the Users API.
If you have an existing authentication system that issues JWTs, you can configure Directus to validate and accept these tokens instead of issuing its own.
This is useful for enterprise scenarios where you want to maintain a single source of truth for authentication, as well as machine-to-machine (M2M) authentication where services need to access Directus programmatically.
::callout{icon="material-symbols:menu-book-outline" color="primary" to="/tutorials/extensions/validating-third-party-jwts-in-directus"} Learn how to validate third-party JWTs in Directus. ::
The default response to any Directus API request is via a JSON payload. It is your responsibility to handle storage and usage of the token.
:partial{content="snippet-auth-token"}
A cookie is a method of storing data in the browser. When using the login endpoint, you may set the mode to session and the Directus response will contain specific headers and the browser will automatically create a directus_session_token cookie on your behalf.
When a request is made to the same Directus domain, the cookie will be automatically included in the request until it expires or is overwritten. As a httpOnly cookie, client-side JavaScript is unable to access it.
To perform actions that are not available to the public role, a valid token must be included in the request.
::tabs
::div{class="pr-6"}
---
label: Authorization Header
---
Add the following header: Authorization: Bearer <token>
::
::div{class="pr-6"}
---
label: Session Cookies
---
You do not need to set anything. The `directus_session_token` is used automatically.
::
::div{class="pr-6"}
---
label: Query Parameter
---
Append the following query parameter: `?access_token=<token>`
::callout{icon="material-symbols:info-outline"}
**Exercise caution when using query parameters for authentication**
Using a query parameter for authentication can lead to it being revealed or logged. If possible, use another method.
::
::
::