GET /:project/users
# Users
Users are what gives you access to the data.
# 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.
# 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.
{
"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
# 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.
GET /:project/users/:id
{
"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.
GET /:project/users/me
{
"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.
POST /:project/users
{
"first_name": "Ben",
"last_name": "Haynes",
"email": "demo@example.com",
"password": "d1r3ctu5",
"role": 3,
"status": "active"
}
{
"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
# 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.
PATCH /:project/users/:id
{
"status": "suspended"
}
{
"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 /: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.
POST /:project/users/invite
{
"email": "demo@example.com"
}
{
"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.
POST /:project/users/invite/:token
{
"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
# 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.
PATCH /:project/users/:id/tracking/page
{
"last_page": "/thumper/settings/"
}
{
"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
# 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.
GET /:project/users/:id/revisions
{
"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.
GET /:project/users/:id/revisions/:offset
{
"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
}
}