Auth

Email Login

Learn about user registration, login with standard/session tokens, refresh, logout, and resetting passwords.

It is most common to authenticate users with an email and password either receiving and storing a standard token or using a session token cookie.

Read more about tokens in Directus.

Registration

Before being able to log in, a user with an email and password must exist. This user can be created manually in the Data Studio, via an invite, or via the Users API.

Read more about creating users.

Login

You can authenticate as a user to receive a standard token.

Logging In

curl \
    --request POST \
    --header 'Content-Type: application/json' \
    --data '{ "email": "hello@example.com", "password": "d1r3ctu5" }' \
    --url 'https://directus.example.com/auth/login'

If the user has two-factor authentication enabled, an otp (one-time password) can be passed as an additional property. The response will contain a standard token.

{
    "expires": 900000,
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "Xp2tTNAdLYfnaAOOjt3oetyCWtobKKUIeEXj..."
}

If you wish to receive and store a session cookie, add a mode property when logging in.

// POST /auth/login

{
  "email": "hello@example.com",
  "password": "d1r3ctu5",
  "mode": "session"
}

// The token won't be returned in JSON response.

Refresh

Retrieve a new access token by refreshing it. The refresh token will be returned in the JSON response or in a httpOnly cookie if the mode parameter is set to json or cookie, respectively.

// POST /auth/refresh

{
  "refresh_token": "Xp2tTNAdLYfnaAOOjt3oetyCWtobKKUIeEXj..."
}

You do not need to provide the refresh_token, but you must specify the mode.

// POST /auth/refresh

{
  "mode": "session"
}

Logout

Invalidate the refresh token and destroy the user's session.

// POST /auth/logout
{
  "refresh_token": "Xp2tTNAdLYfnaAOOjt3oetyCWtobKKUIeEXj..."
}

You can also log out using the http request mechanism:

import { createDirectus, authentication, rest, logout } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(authentication()).with(rest());

const result = await client.request(logout(refresh_token));

You do not need to provide the refresh_token, but you must specify the mode. This will immediately invalidate and delete the cookie.

// POST /auth/refresh

{
  "mode": "session"
}

Password Reset

Requesting a password reset will send an email to the user with a URL to the Data Studio to reset their password.

REST
// POST /auth/password/request

{
  "email": "hello@example.com"
}
An email service must be configured to send password reset requests.

Seamless Password Reset

You can use the password reset system within your own application ensuring users do not need to access the Data Studio.

When using the request reset password endpoint, add a reset_url property. The email will use this URL instead of your Directus project, appending the reset token in the URL as a token parameter.

Your application must extract this value, collect the new user's password, and send both to the reset password endpoint.

// POST /auth/password/reset
{
  "token": "Xp2tTNAdLYfnaAOOjt3oetyCWtobKKUIeEXj",
  "password": "d1r3ctu5!"
}