Skip to content
Return to top
On this page

# 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 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 Attributes #

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

Expiry time

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

### REST API #

    POST /auth/login

    POST /auth/login/:provider

json

    {
    	"email": "admin@example.com",
    	"password": "d1r3ct5us"
    }

### GraphQL #

    POST /graphql/system

graphql

    mutation {
    	auth_login(email: "admin@example.com", password: "d1r3ctu5") {
    		access_token
    		refresh_token
    	}
    }

## Refresh #

Retrieve a new access token using a 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 Attributes #

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

### REST API #

    POST /auth/refresh

json

    {
    	"refresh_token": "gmPd...8wuB",
    	"mode": "json"
    }

### GraphQL #

    POST /graphql/system

graphql

    mutation {
    	auth_refresh(refresh_token: "abc...def", mode: json) {
    		access_token
    		refresh_token
    	}
    }

## Logout #

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

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

### REST API #

    POST /auth/logout

json

    {
    	"refresh_token": "gmPd...8wuB"
    }

### GraphQL #

    POST /graphql/system

graphql

    mutation {
    	auth_logout(refresh_token: "gmPd...8wuB")
    }

## Request Password Reset #

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

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

### REST API #

    POST /auth/password/request

json

    {
    	"email": "admin@example.com"
    }

### GraphQL #

    POST /graphql/system

graphql

    mutation {
    	auth_password_request(email: "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 Body #

`token` Required
Password reset token, as provided in the email sent by the request endpoint.

`password` Required
New password for the user.

### REST API #

    POST /auth/password/reset

json

    {
    	"token": "eyJh...KmUk",
    	"password": "d1r3ctu5"
    }

### GraphQL #

    POST /graphql/system

graphql

    mutation {
    	auth_password_reset(token: "eyJh...KmUk", password: "d1r3ctu5")
    }

## List Auth Providers #

List all the configured auth providers.

Configuring auth providers

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

### Response Attributes #

`data` Array
Array of configured auth providers.

`disableDefault` boolean
Whether or not the default authentication provider is disabled.

    GET /auth

json

    {
    	"data": [
    		{
    			"name": "GitHub",
    			"driver": "oauth2",
    			"icon": "github"
    		},
    		{
    			"name": "Google",
    			"driver": "openid",
    			"icon": "google"
    		},
    		{
    			"name": "Okta",
    			"driver": "openid"
    		}
    	],
    	"disableDefault": false
    }

## Login Using SSO Providers #

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

    GET /auth/login/:provider