13 KiB
description, readTime, pageClass
| description | readTime | pageClass |
|---|---|---|
| API documentation on authentication in Directus. | 5 min read | page-reference |
Authentication
All data within the platform is private by default. The public role can be configured to expose data without authentication, or you can pass an access token to the API to access private data.
Access Tokens
There are two types of tokens that can be used to authenticate within Directus.
Temporary Token (JWT) are returned by the login endpoint/mutation. These tokens have a relatively short
expiration time, and are thus the most secure option to use. The tokens are returned with a refresh_token that can be
used to retrieve a new access token via the refresh endpoint/mutation.
Static Tokens can be set for each platform user, and never expire. They are less secure, but quite useful for
server-to-server communication. They are saved as plain-text within directus_users.token.
Once you have your access token, there are two ways to pass it to the API, via the access_token query parameter, or in
the request's Authorization Header.
Query Parameter
?access_token=<token>
Authorization Header
Authorization: Bearer <token>
Login
Retrieve a temporary access token and refresh token.
Request
POST /auth/login
POST /auth/login/:provider
{
"email": user_email,
"password": user_password
}
POST /graphql/system
mutation {
auth_login(email: "user_email", password: "user_password") {
access_token
refresh_token
}
}
import { createDirectus, authentication, rest, login } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(authentication()).with(rest());
// login using the authentication composable
const result = await client.login(email, password);
// login http request
const result = await client.request(login(email, password));
Request Body
email Required
Email address of the user you're retrieving the access token for.
password Required
Password of the user.
otp
The user's one-time-password (if MFA is enabled).
mode
Whether to retrieve the refresh token in the JSON response, or in a httpOnly secure cookie. One of json, cookie.
Defaults to json.
Response
access_token string
Temporary access token to be used in follow-up requests.
expires integer
How long before the access token will expire. Value is in milliseconds.
refresh_token string
The token that can be used to retrieve a new access token through /auth/refresh. Note: if you used cookie
as the mode in the request, the refresh token won't be returned in the JSON.
::: tip Expiry time
The token's expiration time can be configured through
the ACCESS_TOKEN_TTL environment variable.
:::
Example
POST /auth/login
POST /auth/login/:provider
{
"email": "admin@example.com",
"password": "d1r3ctu5"
}
POST /graphql/system
mutation {
auth_login(email: "admin@example.com", password: "d1r3ctu5") {
access_token
refresh_token
}
}
import { createDirectus, authentication, rest, login } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(authentication()).with(rest());
// login using the authentication composable
const result = await client.login('admin@example.com', 'd1r3ctu5');
// login http request
const result = await client.request(login('admin@example.com', 'd1r3ctu5'));
Refresh
Retrieve a new access token using a refresh token.
Request
POST /auth/refresh
{
"refresh_token": refresh_token_string,
"mode": refresh_mode
}
POST /graphql/system
mutation {
auth_refresh(refresh_token: "abc...def", mode: json) {
access_token
refresh_token
}
}
import { createDirectus, authentication, rest, refresh } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(authentication()).with(rest());
// refresh using the authentication composable
const result = await client.refresh();
// refresh http request using a cookie
const result = await client.request(refresh('cookie'));
// refresh http request using json
const result = await client.request(refresh('json', refresh_token));
Request Body
refresh_token
The refresh token to use. If you have the refresh token in a cookie through /auth/login, you don't have to submit
it here.
mode
Whether to retrieve the refresh token in the JSON response, or in a httpOnly secure cookie. One of json, cookie.
Response
access_token string
Temporary access token to be used in follow-up requests.
expires integer
How long before the access token will expire. Value is in milliseconds.
refresh_token string
The token that can be used to retrieve a new access token through /auth/refresh. Note: if you used cookie
as the mode in the request, the refresh token won't be returned in the JSON.
Example
POST /auth/refresh
{
"refresh_token": "gmPd...8wuB",
"mode": "json"
}
POST /graphql/system
mutation {
auth_refresh(refresh_token: "abc...def", mode: json) {
access_token
refresh_token
}
}
import { createDirectus, authentication, rest, refresh } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(authentication()).with(rest());
// refresh using the authentication composable
const result = await client.refresh();
// refresh http request using a cookie
const result = await client.request(refresh('cookie'));
// refresh http request using json
const result = await client.request(refresh('json', 'gmPd...8wuB'));
Logout
Invalidate the refresh token thus destroying the user's session.
Request
POST /auth/logout
{
"refresh_token": refresh_token
}
POST /graphql/system
mutation {
auth_logout(refresh_token: "refresh_token")
}
import { createDirectus, authentication, rest, logout } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(authentication()).with(rest());
// logout using the authentication composable
const result = await client.logout();
// logout http request
const result = await client.request(logout(refresh_token));
Request Body
refresh_token
The refresh token to invalidate. If you have the refresh token in a cookie through /auth/login, you don't have
to submit it here.
Example
POST /auth/logout
{
"refresh_token": "gmPd...8wuB"
}
POST /graphql/system
mutation {
auth_logout(refresh_token: "gmPd...8wuB")
}
import { createDirectus, authentication, rest, logout } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(authentication()).with(rest());
// logout using the authentication composable
const result = await client.logout();
// logout http request
const result = await client.request(logout('gmPd...8wuB'));
Request Password Reset
Request a password reset email to be sent to the given user.
Request
POST /auth/password/request
{
"email": user_email
}
POST /graphql/system
mutation {
auth_password_request(email: "user_email")
}
import { createDirectus, rest, passwordRequest } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(passwordRequest(user_email));
Request Body
email Required
Email address of the user you're requesting a password reset for.
reset_url
Provide a custom reset url which the link in the email will lead to. The reset token will be passed as a parameter.
Note: You need to configure the
PASSWORD_RESET_URL_ALLOW_LIST environment variable to enable this feature.
Example
POST /auth/password/request
{
"email": "admin@example.com"
}
POST /graphql/system
mutation {
auth_password_request(email: "admin@example.com")
}
import { createDirectus, rest, passwordRequest } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(passwordRequest('admin@example.com'));
Reset a Password
The request a password reset endpoint sends an email with a link to the admin app (or a custom route) which in turn uses this endpoint to allow the user to reset their password.
Request
POST /auth/password/reset
{
"token": password_reset_token,
"password": password
}
POST /graphql/system
mutation {
auth_password_reset(token: "password_reset_token", password: "password")
}
import { createDirectus, rest, passwordReset } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(passwordReset(reset_token, new_password));
Request Body
token Required
Password reset token, as provided in the email sent by the request endpoint.
password Required
New password for the user.
Example
POST /auth/password/reset
{
"token": "eyJh...KmUk",
"password": "d1r3ctu5"
}
POST /graphql/system
mutation {
auth_password_reset(token: "eyJh...KmUk", password: "d1r3ctu5")
}
import { createDirectus, rest, passwordReset } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(passwordReset('reset_token', 'new_password'));
List Auth Providers
List all the configured auth providers.
::: tip Configuring auth providers
To learn more about setting up auth providers, see Configuring auth providers.
:::
Request
GET /auth
import { createDirectus, rest, readProviders } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readProviders());
Response
{
"data": [
{
"name": "GitHub",
"driver": "oauth2",
"icon": "github"
},
{
"name": "Google",
"driver": "openid",
"icon": "google"
},
{
"name": "Okta",
"driver": "openid"
}
],
"disableDefault": false
}
data Array
Array of configured auth providers.
disableDefault boolean
Whether or not the default authentication provider is disabled.
Example
GET /auth
import { createDirectus, rest, readProviders } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(readProviders());
Login Using SSO Providers
Will redirect to the configured SSO provider for the user to login.
Request
GET /auth/login/:provider