Authentication

Authenticate with the Directus REST API

Directus supports multiple authentication methods to suit different use cases.

Public Data

Some data may be accessible without authentication if the Public role has permissions configured.

curl "https://your-directus-instance.com/items/articles"

Temporary Token (JWT)

Login with email and password to receive a temporary access token and refresh token.

Login

email · string · required

User’s email address

password · string · required

User’s password

curl -X POST "https://your-directus-instance.com/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "password"
  }'

Response:

{
  "data": {
    "access_token": "eyJhbGc...",
    "expires": 900000,
    "refresh_token": "abc123..."
  }
}

Using the Token

Include the access token in the Authorization header:

curl "https://your-directus-instance.com/items/articles" \
  -H "Authorization: Bearer eyJhbGc..."

Refresh Token

Access tokens expire after 15 minutes by default. Use the refresh token to get a new access token:

curl -X POST "https://your-directus-instance.com/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "abc123..."
  }'

Logout

Invalidate the refresh token:

curl -X POST "https://your-directus-instance.com/auth/logout" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "abc123..."
  }'

Static Token

For server-to-server communication, use a static token. Create one in Settings > Access Tokens.

curl "https://your-directus-instance.com/items/articles" \
  -H "Authorization: Bearer YOUR_STATIC_TOKEN"

Static tokens never expire. Store them securely and never expose them in client-side code.

SSO Authentication

Directus supports external authentication providers:

OAuth 2.0

# Redirect user to OAuth provider
GET /auth/login/google

OpenID Connect

GET /auth/login/openid

LDAP

curl -X POST "https://your-directus-instance.com/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "password",
    "mode": "ldap"
  }'

SAML

GET /auth/login/saml

See the Authentication Features guide for SSO configuration.

Password Reset

Request Password Reset

curl -X POST "https://your-directus-instance.com/auth/password/request" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]"
  }'

Reset Password

curl -X POST "https://your-directus-instance.com/auth/password/reset" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset-token-from-email",
    "password": "new-password"
  }'

Two-Factor Authentication

Enable TFA for additional security. After login, provide the OTP code:

curl -X POST "https://your-directus-instance.com/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "password",
    "otp": "123456"
  }'

Cookie-Based Sessions

For browser-based applications, use cookie sessions:

SESSION_COOKIE_SECURE=true
SESSION_COOKIE_SAME_SITE=lax

Login returns a cookie that’s automatically sent with subsequent requests.

Error Codes

INVALID_CREDENTIALS · error

Email or password is incorrect

INVALID_TOKEN · error

Access token is invalid or expired

INVALID_OTP · error

Two-factor authentication code is incorrect

USER_SUSPENDED · error

User account has been suspended

Next Steps

Items API

Work with collection items

Users API

Manage users