Email Login
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.
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.
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..."
}
Setting a Cookie
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..."
}
Refreshing a Cookie
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));
Invalidating a Cookie
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.
// POST /auth/password/request
{
"email": "hello@example.com"
}
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!"
}