Users

Users are what gives you access to the data.

Endpoints
   GET /:project/users
   GET /:project/users/:id
   GET /:project/users/me
  POST /:project/users
 PATCH /:project/users/:id
DELETE /:project/users/:id
  POST /:project/users/invite
  POST /:project/users/invite/:token
 PATCH /:project/users/:id/tracking/page
   GET /:project/users/:id/revisions
   GET /:project/users/:id/revisions/:offset

The User Object

Attributes

id integer

Unique identifier for the user.

status string

One of active, invited, draft, suspended, deleted.

role integer

Unique identifier of the role of this user.

first_name string

First name of the user.

last_name string

First name of the user.

email string

Unique email address for the user.

last_access_on datetime

When this user logged in last.

last_page string

Last page that the user was on.

external_id string

ID used for SCIM.

theme string

What theme the user is using. One of light, dark, or auto.

2fa_secret string

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

password_reset_token string

IF the users requests a password reset, this token will be sent in an email.

timezone string

The user's timezone.

locale string

The user's locale used in Directus.

locale_options object

Not currently used. Can be used in the future to allow language overrides like different date formats for locales.

avatar file object

The user's avatar.

company string

The user's company.

title string

The user's title.

email_notifications boolean

Whether or not the user wants to receive notifications per email.

TIP

The user's (hashed) password will never be returned by the API.

User Object
{
  "id": 1,
  "status": "active",
  "role": 1,
  "first_name": "Admin",
  "last_name": "User",
  "email": "admin@example.com",
  "token": "admin",
  "last_access_on": "2020-01-13T19:55:18+00:00",
  "last_page": "/my-project/settings/collections/a",
  "external_id": null,
  "theme": "auto",
  "2fa_secret": null,
  "password_reset_token": null,
  "timezone": "America/New_York",
  "locale": "en-US",
  "locale_options": null,
  "avatar": null,
  "company": null,
  "title": null,
  "email_notifications": true
}

List the users

List the users.

Parameters

project required

The project you're targetting.

Query

fields optional

Control what fields are being returned in the object. Learn more

limit optional

A limit on the number of objects that are returned. Default is 200. Learn more

offset optional

How many items to skip when fetching data. Default is 0. Learn more

sort optional

How to sort the returned items. Learn more

single optional

Return the result as if it was a single item. Useful for selecting a single item based on filters and search queries. Will force limit to be 1. Learn more

status optional

Filter items by the given status. Learn more

filter optional

Select items in collection by given conditions. Learn more

q optional

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

meta optional

What metadata to return in the response. Learn more

Returns

Returns an array of user objects.

Endpoint
   GET /:project/users
Response
{
  "data": [
    {
      "id": 1,
      "status": "active",
      "role": 1,
      "first_name": "Admin",
      "last_name": "User",
      "email": "admin@example.com",
      "token": "admin",
      "last_access_on": "2020-01-13T21:58:56+00:00",
      "last_page": "/my-project/settings/collections/a",
      "external_id": null,
      "theme": "auto",
      "2fa_secret": null,
      "password_reset_token": null,
      "timezone": "America/New_York",
      "locale": "en-US",
      "locale_options": null,
      "avatar": null,
      "company": null,
      "title": null,
      "email_notifications": true
    },
    { ... },
    { ... }
  ]
}

Retrieve a User

Retrieve a single user by unique identifier.

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Query

fields optional

Control what fields are being returned in the object. Learn more

meta optional

What metadata to return in the response. Learn more

Returns

Returns the user object for the given unique identifier.

Endpoint
   GET /:project/users/:id
Response
{
  "data": {
    "id": 5,
    "status": "draft",
    "role": 1,
    "first_name": "Admin",
    "last_name": "User",
    "email": "admin2@example.com",
    "token": null,
    "last_access_on": "2020-01-13T19:55:18+00:00",
    "last_page": "/my-project/settings/collections/a",
    "external_id": null,
    "theme": "auto",
    "2fa_secret": null,
    "password_reset_token": null,
    "timezone": "America/New_York",
    "locale": "en-US",
    "locale_options": null,
    "avatar": null,
    "company": null,
    "title": null,
    "email_notifications": true
  }
}

Retrieve the Current User

Retrieve the currently authenticated user.

TIP

This endpoint doesn't work for the public role.

Parameters

project required

The project you're targetting.

Query

fields optional

Control what fields are being returned in the object. Learn more

meta optional

What metadata to return in the response. Learn more

Returns

Returns the user object for the currently authenticated user.

Endpoint
   GET /:project/users/me
Response
{
  "data": {
    "id": 1,
    "status": "active",
    "role": 1,
    "first_name": "Admin",
    "last_name": "User",
    "email": "admin@example.com",
    "token": "admin",
    "last_access_on": "2020-01-13T21:58:56+00:00",
    "last_page": "/my-project/settings/collections/a",
    "external_id": null,
    "theme": "auto",
    "2fa_secret": null,
    "password_reset_token": null,
    "timezone": "America/New_York",
    "locale": "en-US",
    "locale_options": null,
    "avatar": null,
    "company": null,
    "title": null,
    "email_notifications": true
  }
}

Create a User

Create a new user.

Parameters

project required

The project you're targetting.

Attributes

status required

One of active, invited, draft, suspended, deleted.

role required

Unique identifier of the role of this user.

first_name required

First name of the user.

last_name required

Last name of the user.

email required

Unique email address for the user.

password required

Password for the new user.

last_access_on optional

When this user logged in last.

last_page optional

Last page that the user was on.

external_id optional

ID used for SCIM.

theme optional

What theme the user is using. One of light, dark, or auto.

2fa_secret optional

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

password_reset_token optional

IF the users requests a password reset, this token will be sent in an email.

timezone optional

The user's timezone.

locale optional

The user's locale used in Directus.

locale_options optional

Not currently used. Can be used in the future to allow language overrides like different date formats for locales.

avatar optional object

The user's avatar.

company optional

The user's company.

title optional

The user's title.

email_notifications optional

Whether or not the user wants to receive notifications per email.

Query

meta optional

What metadata to return in the response. Learn more

Returns

Returns the user object for the user that was just created.

Endpoint
  POST /:project/users
Request
{
  "first_name": "Ben",
  "last_name": "Haynes",
  "email": "demo@example.com",
  "password": "d1r3ctu5",
  "role": 3,
  "status": "active"
}
Response
{
  "data": {
    "id": 14,
    "status": "active",
    "role": 3,
    "first_name": "Ben",
    "last_name": "Haynes",
    "email": "demo@example.com",
    "token": null,
    "last_access_on": null,
    "last_page": null,
    "external_id": "53eece97-d84c-4940-9a6d-be2d4db07dc3",
    "theme": "auto",
    "2fa_secret": null,
    "password_reset_token": null,
    "timezone": "America/New_York",
    "locale": null,
    "locale_options": null,
    "avatar": null,
    "company": null,
    "title": null,
    "email_notifications": true
  }
}

Update a User

Update an existing user

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Attributes

status optional

One of active, invited, draft, suspended, deleted.

role optional

Unique identifier of the role of this user.

first_name optional

First name of the user.

last_name optional

First name of the user.

email optional

Unique email address for the user.

password optional

Password for the new user.

last_access_on optional

When this user logged in last.

last_page optional

Last page that the user was on.

external_id optional

ID used for SCIM.

theme optional

What theme the user is using. One of light, dark, or auto.

2fa_secret optional

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

password_reset_token optional

IF the users requests a password reset, this token will be sent in an email.

timezone optional

The user's timezone.

locale optional

The user's locale used in Directus.

locale_options optional

Not currently used. Can be used in the future to allow language overrides like different date formats for locales.

avatar optional object

The user's avatar.

company optional

The user's company.

title optional

The user's title.

email_notifications optional

Whether or not the user wants to receive notifications per email.

Query

fields optional

Control what fields are being returned in the object. Learn more

meta optional

What metadata to return in the response. Learn more

Returns

Returns the user object for the user that was just updated.

Endpoint
 PATCH /:project/users/:id
Request
{
  "status": "suspended"
}
Response
{
  "data": {
    "id": 14,
    "status": "suspended",
    "role": 3,
    "first_name": null,
    "last_name": null,
    "email": "demo@example.com",
    "token": null,
    "last_access_on": null,
    "last_page": null,
    "external_id": "53eece97-d84c-4940-9a6d-be2d4db07dc3",
    "theme": "auto",
    "2fa_secret": null,
    "password_reset_token": null,
    "timezone": "America/New_York",
    "locale": null,
    "locale_options": null,
    "avatar": null,
    "company": null,
    "title": null,
    "email_notifications": true
  }
}

Delete a User

Delete an existing user

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Returns

Returns an empty body with HTTP status 204

Endpoint
DELETE /:project/users/:id

Invite a New User

Invites one or more users 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.

Parameters

project required

The project you're targetting.

Attributes

email required

Email address or array of email addresses of the to-be-invited user(s).

Query

No query parameters available.

Returns

The newly created user object.

Endpoint
  POST /:project/users/invite
Request
{
  "email": "demo@example.com"
}
Response
{
  "data": [
    {
      "id": 18,
      "status": "invited",
      "role": null,
      "first_name": null,
      "last_name": null,
      "email": "demo@example.com",
      "token": null,
      "last_access_on": null,
      "last_page": null,
      "external_id": "fba6f42d-cc99-4f6a-a620-51000001f355",
      "theme": "auto",
      "2fa_secret": null,
      "password_reset_token": null,
      "timezone": "America/New_York",
      "locale": null,
      "locale_options": null,
      "avatar": null,
      "company": null,
      "title": null,
      "email_notifications": true
    }
  ]
}

Accept User Invite

Accepts and enables an invited user using a JWT invitation token.

Parameters

project required

The project you're targetting.

token required jwt

JWT token that was sent in the email.

Attributes

No attributes available.

Query

No query parameters available.

Returns

The activated user object.

Endpoint
  POST /:project/users/invite/:token
Response
{
  "data": {
    "id": 20,
    "status": "active",
    "role": null,
    "first_name": null,
    "last_name": null,
    "email": "demo@example.com",
    "token": null,
    "last_access_on": null,
    "last_page": null,
    "external_id": "389ffc3e-359c-4ee1-b301-14ba10b36ef4",
    "theme": "auto",
    "2fa_secret": null,
    "password_reset_token": null,
    "timezone": "America/New_York",
    "locale": null,
    "locale_options": null,
    "avatar": null,
    "company": null,
    "title": null,
    "email_notifications": true
  }
}

Track the Last Used Page

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

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Attributes

last_page required

Path of the page you used last.

Query

No query parameters available.

Returns

Returns the user object of the user that was just updated.

Endpoint
 PATCH /:project/users/:id/tracking/page
Request
{
  "last_page": "/thumper/settings/"
}
Response
{
  "data": {
    "id": 15,
    "status": "active",
    "role": 3,
    "first_name": null,
    "last_name": null,
    "email": "sdf@example.com",
    "token": null,
    "last_access_on": "2020-01-13T22:31:43+00:00",
    "last_page": "/thumper/setting/",
    "external_id": "f8e90dec-b6ec-4149-b1f1-c6717b24d70c",
    "theme": "auto",
    "2fa_secret": null,
    "password_reset_token": null,
    "timezone": "America/New_York",
    "locale": null,
    "locale_options": null,
    "avatar": null,
    "company": null,
    "title": null,
    "email_notifications": true
  }
}

List User Revisions

List the revisions made to the given user.

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Query

fields optional

Control what fields are being returned in the object. Learn more

limit optional

A limit on the number of objects that are returned. Default is 200. Learn more

offset optional

How many items to skip when fetching data. Default is 0. Learn more

page optional

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

sort optional

How to sort the returned items. Learn more

single optional

Return the result as if it was a single item. Useful for selecting a single item based on filters and search queries. Will force limit to be 1. Learn more

filter optional

Select items in collection by given conditions. Learn more

q optional

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

meta optional

What metadata to return in the response. Learn more

Returns

Returns an array of revision objects.

Endpoint
   GET /:project/users/:id/revisions
Response
{
  "data": [
    {
      "id": 35,
      "activity": 37,
      "collection": "directus_users",
      "item": "15",
      "data": {
        "id": "15",
        "status": "active",
        "role": "3",
        "first_name": null,
        "last_name": null,
        "email": "sdf@example.com",
        "token": null,
        "last_access_on": null,
        "last_page": null,
        "external_id": "f8e90dec-b6ec-4149-b1f1-c6717b24d70c",
        "theme": "auto",
        "2fa_secret": null,
        "password_reset_token": null,
        "timezone": "America/New_York",
        "locale": null,
        "locale_options": null,
        "avatar": null,
        "company": null,
        "title": null,
        "email_notifications": true
      },
      "delta": {
        "status": "active"
      },
      "parent_collection": null,
      "parent_item": null,
      "parent_changed": false
    },
    { ... },
    { ... }
  ]
}

Retrieve a User Revision

Retrieve a single revision of the user by offset.

Parameters

project required

The project you're targetting.

offset required

How many revisions to go back in time.

Query

fields optional

Control what fields are being returned in the object. Learn more

meta optional

What metadata to return in the response. Learn more

Returns

Returns the revision object for the given unique identifier.

Endpoint
   GET /:project/users/:id/revisions/:offset
Response
{
  "data": {
    "id": 39,
    "activity": 44,
    "collection": "directus_users",
    "item": "15",
    "data": {
      "id": "15",
      "status": "active",
      "role": "3",
      "first_name": null,
      "last_name": null,
      "email": "sdf@example.com",
      "token": null,
      "last_access_on": "2020-01-13 22:31:43",
      "last_page": "/thumper/setting/",
      "external_id": "f8e90dec-b6ec-4149-b1f1-c6717b24d70c",
      "theme": "auto",
      "2fa_secret": null,
      "password_reset_token": null,
      "timezone": "America/New_York",
      "locale": null,
      "locale_options": null,
      "avatar": null,
      "company": null,
      "title": null,
      "email_notifications": true
    },
    "delta": [],
    "parent_collection": null,
    "parent_item": null,
    "parent_changed": false
  }
}