Appearance

On this page

Directus Cloud

Everything you need to start building. Provisioned in 90 seconds. Starting at $15/month.

Get Started

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 three 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.

Session Token (JWT) can also be returned by the login endpoint/mutation.
Session tokens combine both a refresh token and access token in a single cookie. These tokens should not have a short expiration time like the Temporary Tokens as you cannot refresh these after they have expired.

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. Static Tokens are created in user settings inside of the Directus Data Studio User Module, or by updating the user's token value via API.

Once you have your access token, there are three ways to pass it to the API: in the request's Authorization Header, as session cookie or via the access_token query parameter.

Authorization Header ​

Authorization: Bearer <token>
Authorization: Bearer <token>
Cookie: directus_session_token=<token>
Cookie: directus_session_token=<token>

Query Parameter ​

?access_token=<token>
?access_token=<token>

WARNING

The query parameter option is not recommended in production setups as the parameter can get logged by various systems.

Register ​

Register a new user.

Disabled by Default

The user registration feature is disabled by default. To make use of it, it must first be enabled via Project Settings.

Register vs Create User

You can also use the create user endpoint, but this will require the correct permissions on the directus_users collection. The register endpoint is publicly available if enabled in your project.

Request ​

Request Body ​

email Required
Email address of the user.

password Required
Password of the user.

first_name
First name of the user.

last_name
Last name of the user.

verification_url
Provide a custom verification URL for the verification email. The verification token will be appended to this URL as a query parameter.
Note: Only URLs that are configured via the USER_REGISTER_URL_ALLOW_LIST environment variable will be accepted.

Example ​

Verify a Registration ​

If enabled in project settings, registering a user sends a verification email with a link to this endpoint (or a custom URL) to allow the user to finish their registration.

Request ​

Request Body ​

token Required
Verification token, as provided in the verification email sent by the registration endpoint.

Example ​

Login ​

Authenticate as a user.

Request ​

Request Body ​

email Required
Email address of the user.

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 cookie. One of json, cookie or session. Defaults to json.

Response ​

access_token string
Temporary access token to be used in follow-up requests. Note: if you used session as the mode in the request, the access token won't be returned in the JSON.

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 or session as the mode in the request, the refresh token won't be returned in the JSON.

Expiry time

The token's expiration time can be configured through the ACCESS_TOKEN_TTL environment variable.

Example ​

Refresh ​

Retrieve a new access token using a refresh token.

Request ​

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 submit and retrieve the refresh token in the JSON response, or in a httpOnly cookie. One of json, cookie or session.

Response ​

access_token string
Temporary access token to be used in follow-up requests. Note: if you used session as the mode in the request, the access token won't be returned in the JSON.

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 or session as the mode in the request, the refresh token won't be returned in the JSON.

Example ​

Logout ​

Invalidate the refresh token thus destroying the user's session.

Request ​

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.

mode
Whether the refresh token is submitted in the JSON response, or in a httpOnly cookie. One of json, cookie or session.

Example ​

Request Password Reset ​

Request a password reset email to be sent to the given user.

Request ​

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 ​

Reset a Password ​

The request a password reset endpoint sends an email with a link to the Data Studio (or a custom route) which in turn uses this endpoint to allow the user to reset their password.

Request ​

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 ​

List Auth Providers ​

List all the configured auth providers.

Configuring auth providers

To learn more about setting up auth providers, see Configuring auth providers.

Request ​

Response ​

json
{
	"data": [
		{
			"name": "GitHub",
			"driver": "oauth2",
			"icon": "github"
		},
		{
			"name": "Google",
			"driver": "openid",
			"icon": "google"
		},
		{
			"name": "Okta",
			"driver": "openid"
		}
	],
	"disableDefault": false
}
{
	"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 ​

Login Using SSO Providers ​

Will redirect to the configured SSO provider for the user to login.

Request ​