Directus Docs

Legacy Version

These are the docs for Directus 8, a legacy version of the platform. If you're looking for the current Directus 9 documentation, go here: https://docs.directus.io

Authentication

By default, all data in the system is off limits for unauthenticated users. To gain access to protected data, you must include an access token with every request.

Endpoints
  POST /:project/auth/authenticate
  POST /:project/auth/refresh
  POST /:project/auth/password/request
  POST /:project/auth/password/reset
   GET /:project/auth/sso
   GET /:project/auth/sso/:provider
   GET /:project/auth/sso/:provider/callback

Tokens

Tokens can be passed in one of three ways:

Authorization Header

Authorization: bearer <token>

By default, apache servers strip the Authentication header from requests, and blocks directus from seeing it. Adding the option 'CGIPassAuth On' to the directory statement in the site configuration in apache will resolve this.

<Directory /var/www/directus/public/>
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
    CGIPassAuth On
</Directory>

Query Parameter

?access_token=<token>

When authenticating through the /auth/authenticate endpoint, you can instruct the API to set a cookie instead of returning the token as a string. This is the most secure option for building web-based applications, as this cookie can't be read from client side JavaScript. This cookie will also automatically refresh as long as you use it.

Cookie: directus-<project>-session=<token>

There are two types of tokens:

Temporary (JWT)

These tokens are generated through the /auth/authenticate endpoint (below) and have a lifespan of 20 minutes. These tokens can be refreshed using the /auth/refresh endpoint.

Static token

Each user can have one static token that will never expire. This is useful for server-to-server communication, but is also less secure than the JWT token. Static tokens can only be set through the database directly in the directus_users.token column.

TIP

See the Authenticate endpoint down below to learn how to retrieve a token.

Retrieve a Temporary Access Token

Parameters

project required

The project you're targetting.

Attributes

email required

Email address of the user you're retrieving the access token for.

password required

Password of the user.

mode optional

Choose between retrieving the token as a string, or setting it as a cookie. One of jwt, cookie. Defaults to jwt.

otp optional

If 2FA is enabled, you need to pass the one time password.

Query

No query parameters available.

Returns

Returns the token (if jwt mode is used) and the user record for the user you just authenticated as.

Endpoint
  POST /:project/auth/authenticate
Request
{
  "email": "admin@example.com",
  "password": "password"
}
Response
{
  "data": {
    "token": "eyJ0eXAiOi...",
    "user": {
      "id": "1",
      "status": "active",
      "role": "1",
      "first_name": "Admin",
      "last_name": "User",
      "email": "admin@example.com",
      "timezone": "America/New_York",
      "locale": "en-US",
      "locale_options": null,
      "avatar": null,
      "company": null,
      "title": null,
      "external_id": null,
      "theme": "auto",
      "2fa_secret": null,
      "password_reset_token": null
    }
  },
  "public": true
}

Refresh a Temporary Access Token

Cookie mode

You don't have to use this is you're using cookies for authentication.

Parameters

project required

The project you're targetting.

Attributes

token required

JWT access token you want to refresh. This token can't be expired.

Query

No query parameters available.

Returns

Returns the new token.

Endpoint
  POST /:project/auth/refresh
Request
{
  "token": "eyJ0eXAiOiJKV..."
}
Response
{
  "data": {
    "token": "eyJ0eXAiOiJ..."
  },
  "public": true
}

Request a Password Reset

Request a reset password email to be send.

Parameters

project required

The project you're targetting.

Attributes

email required

Email address of the user you're requesting a reset for.

reset_url optional

Provide a custom reset url which the link in the Email will lead to. The reset token will be passed as a parameter.

Query

No query parameters available.

Returns

Sends the email. No data is returned.

Endpoint
  POST /:project/auth/password/request
Request
{
  "email": "admin@example.com",
  "reset_url": "https://mydomain/passwordreset"
}

Reset a Password

The request a password reset endpoint sends an email with a link to the admin app which in turn uses this endpoint to allow the user to reset their password.

Parameters

project required

The project you're targetting.

Attributes

password required

New password for the user.

token required

One-time use JWT token that is used to verify the user.

Query

No query parameters available.

Returns

Resets the password. No data is returned.

Endpoint
  POST /:project/auth/password/reset
Request
{
  "token": "eyJ0eXAiOiJKV1Qi...",
  "password": "test"
}

List the SSO Providers

List the SSO providers.

Parameters

project required

The project you're targetting.

Query

No query parameters available.

Returns

Returns an array of active SSO provider names.

Endpoint
   GET /:project/auth/sso
Response
{
  "data": ["github", "facebook"],
  "public": true
}

Open SSO Provider

Opens the provided SSO provider's login page.

Parameters

project required

The project you're targetting.

provider required

Key of the activated SSO provider.

Query

mode required

Controls if the API sets a cookie or returns a JWT on successful login. One of jwt, cookie

redirect_url required

Where to redirect on successful login.

Returns

Opens the provider's login page.

Endpoint
   GET /:project/auth/sso/:provider

SSO Callback

This shouldn't be called by your project directly. This is the URL configured in your SSO provider to redirect to on successful login.

Parameters

project required

The project you're targetting.

provider required

Key of the activated SSO provider.

Query

Relies on the SSO provider to pass the correct query parameters.

Returns

The token if jwt mode is used, or sets a cookie and redirects to redirect_url from the Open SSO Provider request if cookie mode is used.

Endpoint
   GET /:project/auth/sso/:provider/callback

← Items →