Users

Directus Users are the individual accounts that let you authenticate into the API and App. Each user can belong to a Role.

List Users

List all users that exist in Directus.

Query Parameters

fields
array

Control what fields are being returned in the object.

limit
integer

A limit on the number of objects that are returned.

offset
integer

How many items to skip when fetching data.

meta
string

What metadata to return in the response.

sort
array

How to sort the returned items. sort is a CSV of fields used to sort the fetched items. Sorting defaults to ascending (ASC) order but a minus sign (-) can be used to reverse this to descending (DESC) order. Fields are prioritized by their order in the CSV. You can also use a ? to sort randomly.

filter

Select items in collection by given conditions.

search
string

Filter by items that contain the given search query in one of their fields.

Response

Successful request

data
array
meta
object
GET /users
Response Example
{
  "data": [
    {
      "id": "63716273-0f29-4648-8a2a-2af2948f6f78",
      "first_name": "Admin",
      "last_name": "User",
      "email": "admin@example.com",
      "location": null,
      "title": null,
      "description": null,
      "tags": null,
      "avatar": null,
      "language": "en-US",
      "tfa_secret": null,
      "status": "active",
      "role": "2f24211d-d928-469a-aea3-3c8f53d4e426",
      "policies": "2f24211d-d928-469a-aea3-3c8f53d4e426",
      "last_access": "2020-05-31T14:32:37Z",
      "last_page": "/my-project/settings/collections/a",
      "auth_data": {},
      "theme_light_overrides": {},
      "theme_dark_overrides": {}
    }
  ],
  "meta": {}
}

Create Multiple Users

Create multiple new users.

Query Parameters

fields
array

Control what fields are being returned in the object.

limit
integer

A limit on the number of objects that are returned.

offset
integer

How many items to skip when fetching data.

meta
string

What metadata to return in the response.

sort
array

How to sort the returned items. sort is a CSV of fields used to sort the fetched items. Sorting defaults to ascending (ASC) order but a minus sign (-) can be used to reverse this to descending (DESC) order. Fields are prioritized by their order in the CSV. You can also use a ? to sort randomly.

filter

Select items in collection by given conditions.

search
string

Filter by items that contain the given search query in one of their fields.

page
integer

Cursor for use in pagination. Often used in combination with limit.

Request Body

`email` and `password` are required.

data
array

Response

Successful request

data
array
meta
object
POST /users
Response Example
{
  "data": [
    {
      "id": "63716273-0f29-4648-8a2a-2af2948f6f78",
      "first_name": "Admin",
      "last_name": "User",
      "email": "admin@example.com",
      "location": null,
      "title": null,
      "description": null,
      "tags": null,
      "avatar": null,
      "language": "en-US",
      "tfa_secret": null,
      "status": "active",
      "role": "2f24211d-d928-469a-aea3-3c8f53d4e426",
      "policies": "2f24211d-d928-469a-aea3-3c8f53d4e426",
      "last_access": "2020-05-31T14:32:37Z",
      "last_page": "/my-project/settings/collections/a",
      "auth_data": {},
      "theme_light_overrides": {},
      "theme_dark_overrides": {}
    }
  ],
  "meta": {}
}

Delete Multiple Users

Delete multiple existing users.

Query Parameters

Request Body

An array of user primary keys.

[array]
array
DELETE /users

Update Multiple Users

Update multiple users at the same time.

Query Parameters

fields
array

Control what fields are being returned in the object.

limit
integer

A limit on the number of objects that are returned.

meta
string

What metadata to return in the response.

offset
integer

How many items to skip when fetching data.

sort
array

How to sort the returned items. sort is a CSV of fields used to sort the fetched items. Sorting defaults to ascending (ASC) order but a minus sign (-) can be used to reverse this to descending (DESC) order. Fields are prioritized by their order in the CSV. You can also use a ? to sort randomly.

filter

Select items in collection by given conditions.

search
string

Filter by items that contain the given search query in one of their fields.

Request Body

data
object
keys
array

Response

Successful request

data
array
meta
object
PATCH /users
Response Example
{
  "data": [
    {
      "id": "63716273-0f29-4648-8a2a-2af2948f6f78",
      "first_name": "Admin",
      "last_name": "User",
      "email": "admin@example.com",
      "location": null,
      "title": null,
      "description": null,
      "tags": null,
      "avatar": null,
      "language": "en-US",
      "tfa_secret": null,
      "status": "active",
      "role": "2f24211d-d928-469a-aea3-3c8f53d4e426",
      "policies": "2f24211d-d928-469a-aea3-3c8f53d4e426",
      "last_access": "2020-05-31T14:32:37Z",
      "last_page": "/my-project/settings/collections/a",
      "auth_data": {},
      "theme_light_overrides": {},
      "theme_dark_overrides": {}
    }
  ],
  "meta": {}
}

Create an User

Create a new user.

Query Parameters

fields
array

Control what fields are being returned in the object.

meta
string

What metadata to return in the response.

Request Body

[object]
object

Response

Successful request

data
object
POST /users‎
Response Example
{
  "data": {
    "id": "63716273-0f29-4648-8a2a-2af2948f6f78",
    "first_name": "Admin",
    "last_name": "User",
    "email": "admin@example.com",
    "location": null,
    "title": null,
    "description": null,
    "tags": null,
    "avatar": null,
    "language": "en-US",
    "tfa_secret": null,
    "status": "active",
    "role": "2f24211d-d928-469a-aea3-3c8f53d4e426",
    "policies": "2f24211d-d928-469a-aea3-3c8f53d4e426",
    "last_access": "2020-05-31T14:32:37Z",
    "last_page": "/my-project/settings/collections/a",
    "auth_data": {},
    "theme_light_overrides": {},
    "theme_dark_overrides": {}
  }
}

Retrieve a User

List an existing user by primary key.

Query Parameters

id
string

Unique identifier for the object.

fields
array

Control what fields are being returned in the object.

meta
string

What metadata to return in the response.

Response

Successful request

data
object
GET /users/{id}
Response Example
{
  "data": {
    "id": "63716273-0f29-4648-8a2a-2af2948f6f78",
    "first_name": "Admin",
    "last_name": "User",
    "email": "admin@example.com",
    "location": null,
    "title": null,
    "description": null,
    "tags": null,
    "avatar": null,
    "language": "en-US",
    "tfa_secret": null,
    "status": "active",
    "role": "2f24211d-d928-469a-aea3-3c8f53d4e426",
    "policies": "2f24211d-d928-469a-aea3-3c8f53d4e426",
    "last_access": "2020-05-31T14:32:37Z",
    "last_page": "/my-project/settings/collections/a",
    "auth_data": {},
    "theme_light_overrides": {},
    "theme_dark_overrides": {}
  }
}

Delete a User

Delete an existing user.

Query Parameters

id
string

Unique identifier for the object.

DELETE /users/{id}

Update a User

Update an existing user.

Query Parameters

id
string

Unique identifier for the object.

fields
array

Control what fields are being returned in the object.

meta
string

What metadata to return in the response.

Request Body

id
string

Unique identifier for the user.

first_name
string

First name of the user.

last_name
string

Last name of the user.

email
string

Unique email address for the user.

password
string

Password of the user.

location
string

The user's location.

title
string

The user's title.

description
string

The user's description.

tags
array

The user's tags.

avatar
string

The user's avatar. Many-to-one to files.

language
string

The user's language used in Directus. Language the Data Studio is rendered in. See our Crowdin page for all available languages and translations.

tfa_secret
string

The 2FA secret string that's used to generate one time passwords.

status
string

Status of the user.

role
string

Unique identifier of the role of this user. Many-to-one to roles.

token
string

Static token for the user.

policies
string

The policies associated with this user. Many-to-many to policies.

last_access
string

When this user used the API last.

last_page
string

Last page that the user was on.

provider
string

What auth provider was used to register this user.

external_identifier
string

Primary key of the user in the third party authentication provider, if used.

auth_data
object

Required data about the user as provided by the third party auth provider, if used.

email_notifications
boolean

When this is enabled, the user will receive emails for notifications.

appearance
string

One of auto, light, dark.

theme_dark
string

Theme to use in dark mode.

theme_light
string

Theme to use in light mode.

theme_light_overrides
object

Customization for light theme in use.

theme_dark_overrides
object

Customization for dark theme in use.

Response

Successful request

data
object
PATCH /users/{id}
Response Example
{
  "data": {}
}

Invite User

Invites a user to this project. It creates a user with an invited status, and then sends an email to the user with instructions on how to activate their account.

Query Parameters

Request Body

email
string

Email address of the to-be-invited user.

role
string

Role of the new user

invite_url
string

Provide a custom invite url which the link in the email will lead to. The invite token will be passed as a parameter. Note: You need to configure the USER_INVITE_URL_ALLOW_LIST environment variable to enable this feature.

POST /users/invite

Accept User Invite

Accept your invite. The invite user endpoint sends the email a link to the Data Studio. This link includes a token, which is then used to activate the invited user.

Query Parameters

Request Body

token
string

Accept invite token.

password
string

Password of the user.

POST /users/invite/accept

Retrieve Current User

Retrieve the currently authenticated user.

Query Parameters

fields
array

Control what fields are being returned in the object.

meta
string

What metadata to return in the response.

Response

Successful request

data
object
GET /users/me
Response Example
{
  "data": {
    "id": "63716273-0f29-4648-8a2a-2af2948f6f78",
    "first_name": "Admin",
    "last_name": "User",
    "email": "admin@example.com",
    "location": null,
    "title": null,
    "description": null,
    "tags": null,
    "avatar": null,
    "language": "en-US",
    "tfa_secret": null,
    "status": "active",
    "role": "2f24211d-d928-469a-aea3-3c8f53d4e426",
    "policies": "2f24211d-d928-469a-aea3-3c8f53d4e426",
    "last_access": "2020-05-31T14:32:37Z",
    "last_page": "/my-project/settings/collections/a",
    "auth_data": {},
    "theme_light_overrides": {},
    "theme_dark_overrides": {}
  }
}

Update Current User

Update the currently authenticated user.

Query Parameters

fields
array

Control what fields are being returned in the object.

meta
string

What metadata to return in the response.

Response

Successful request

data
object
PATCH /users/me
Response Example
{
  "data": {
    "id": "63716273-0f29-4648-8a2a-2af2948f6f78",
    "first_name": "Admin",
    "last_name": "User",
    "email": "admin@example.com",
    "location": null,
    "title": null,
    "description": null,
    "tags": null,
    "avatar": null,
    "language": "en-US",
    "tfa_secret": null,
    "status": "active",
    "role": "2f24211d-d928-469a-aea3-3c8f53d4e426",
    "policies": "2f24211d-d928-469a-aea3-3c8f53d4e426",
    "last_access": "2020-05-31T14:32:37Z",
    "last_page": "/my-project/settings/collections/a",
    "auth_data": {},
    "theme_light_overrides": {},
    "theme_dark_overrides": {}
  }
}

Disable Two-Factor Authentication

Disables two-factor authentication for the currently authenticated user.

Query Parameters

Request Body

otp
string

One-time password generated by the authenticator app.

POST /users/me/tfa/disable

Enable 2FA

Enables two-factor authentication for the currently authenticated user.

Query Parameters

Request Body

secret
string

The TFA secret from tfa/generate.

otp
string

OTP generated with the secret, to recheck if the user has a correct TFA setup

POST /users/me/tfa/enable

Generate Two-Factor Authentication Secret

Generates a secret and returns the URL to be used in an authenticator app.

Query Parameters

Request Body

[string]
string

Response

Successful request

secret
string

OTP secret to be saved in the authenticator app.

otpauth_url
string

otpauth:// formatted URL. Can be rendered as QR code and used in most authenticator apps.

POST /users/me/tfa/generate
Response Example
{}

Update Last Page

Updates the last used page field of the currently authenticated user. This is used internally to be able to open the Directus admin app from the last page you used.

Query Parameters

Request Body

last_page
string

Path of the page you used last.

Register a new User

Register a new user.

Query Parameters

fields
array

Control what fields are being returned in the object.

meta
string

What metadata to return in the response.

Request Body

email
string

Email for the new user.

password
string

Password for the new user.

first_name
string

First name for the new user.

last_name
string

Last name for the new user.

verification_url
string

Provide a custom verification url which the link in the email will lead to. The verification token will be passed as a parameter. Note: You need to configure the USER_REGISTER_URL_ALLOW_LIST environment variable to enable this feature.

POST /users/register

Verify Registered Email

Verify the registered email address. The register user endpoint sends the email a link for verification. This link includes a token, which is then used to activate the registered user.

Query Parameters

token
string

Emailed registration token.

GET /users/register/verify-email/{token}