directus/docs/reference/api/rest/users.md

pageClass

pageClass
page-reference

Users

Directus Users are the individual accounts that let you authenticate into the API and App. Each user belongs to a Role which defines its granular Permissions. Learn more about Users.

toc

---

The User Object

id uuid
Primary key of the user.

first_name string
First name of the user.

last_name string
Last name of the user.

email string
Email address of the user.

password hash
Password of the user.

location string
Location of the user.

title string
Title of the user.

description string
Description of the user.

tags csv
Tags for the user.

avatar many-to-one
Avatar file. Many-to-one to files.

language string
Language the Admin App is rendered in. See our Crowdin page for all available languages and translations.

theme string
One of auto, light, dark.

tfa_secret string
When TFA is enabled, this holds the

{
	"id": "0bc7b36a-9ba9-4ce0-83f0-0a526f354e07",
	"first_name": "Admin",
	"last_name": "User",
	"email": "admin@example.com",
	"password": "**********",
	"location": "New York City",
	"title": "CTO",
	"description": null,
	"tags": null,
	"avatar": null,
	"language": "en-US",
	"theme": "auto",
	"tfa_secret": null,
	"status": "active",
	"role": "653925a9-970e-487a-bfc0-ab6c96affcdc",
	"token": null,
	"last_access": "2021-02-05T10:18:13-05:00",
	"last_page": "/settings/roles/653925a9-970e-487a-bfc0-ab6c96affcdc"
}

---

List Users

List all users that exist in Directus.

Query Parameters

Supports all global query parameters.

Returns

An array of up to limit user objects. If no items are available, data will be an empty array.

GET /users

// Response

{
	"data": [
		{
			"id": "0bc7b36a-9ba9-4ce0-83f0-0a526f354e07",
			"first_name": "Admin",
			"last_name": "User",
			"email": "admin@example.com",
			"password": "**********",
			"location": "New York City",
			"title": "CTO",
			"description": null,
			"tags": null,
			"avatar": null,
			"language": "en-US",
			"theme": "auto",
			"tfa_secret": null,
			"status": "active",
			"role": "653925a9-970e-487a-bfc0-ab6c96affcdc",
			"token": null,
			"last_access": "2021-02-05T10:18:13-05:00",
			"last_page": "/settings/roles/653925a9-970e-487a-bfc0-ab6c96affcdc"
		},
		{...},
		{...}
	]
}

---

Retrieve a User

List an existing user by primary key.

Query Parameters

Supports all global query parameters.

Returns

Returns the requested user object.

GET /users/:id

// Response

{
	"data": {
		"id": "0bc7b36a-9ba9-4ce0-83f0-0a526f354e07",
		"first_name": "Admin",
		"last_name": "User",
		"email": "admin@example.com",
		"password": "**********",
		"location": "New York City",
		"title": "CTO",
		"description": null,
		"tags": null,
		"avatar": null,
		"language": "en-US",
		"theme": "auto",
		"tfa_secret": null,
		"status": "active",
		"role": "653925a9-970e-487a-bfc0-ab6c96affcdc",
		"token": null,
		"last_access": "2021-02-05T10:18:13-05:00",
		"last_page": "/settings/roles/653925a9-970e-487a-bfc0-ab6c96affcdc"
	}
}

---

Retrieve the Current User

Retrieve the currently authenticated user.

Query Parameters

Supports all global query parameters.

Returns

Returns the user object for the currently authenticated user.

GET /users/me

// Response

{
	"data": {
		"id": "0bc7b36a-9ba9-4ce0-83f0-0a526f354e07",
		"first_name": "Admin",
		"last_name": "User",
		"email": "admin@example.com",
		"password": "**********",
		"location": "New York City",
		"title": "CTO",
		"description": null,
		"tags": null,
		"avatar": null,
		"language": "en-US",
		"theme": "auto",
		"tfa_secret": null,
		"status": "active",
		"role": "653925a9-970e-487a-bfc0-ab6c96affcdc",
		"token": null,
		"last_access": "2021-02-05T10:18:13-05:00",
		"last_page": "/settings/roles/653925a9-970e-487a-bfc0-ab6c96affcdc"
	}
}

---

Create a User

Create one or more new user(s).

Query Parameters

Supports all global query parameters.

Request Body

A partial user object or an array of partial user objects.

email and password are required.

Returns

Returns the user object(s) for the created user(s).

POST /users

// Request

{
	"email": "another@example.com",
	"password": "d1r3ctu5",
	"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
}

// Response

{
	"data": {
		"id": "b917be29-e326-4597-ad73-ff892be35aac",
		"first_name": null,
		"last_name": null,
		"email": "another@example.com",
		"password": "**********",
		"location": null,
		"title": null,
		"description": null,
		"tags": null,
		"avatar": null,
		"language": "en-US",
		"theme": "auto",
		"tfa_secret": null,
		"status": "active",
		"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
		"token": null,
		"last_access": null,
		"last_page": null
	}
}

---

Update a User

Update an existing user.

Query Parameters

Supports all global query parameters.

Request Body

A partial user object.

Returns

Returns the user object for the created user.

PATCH /users/:id

// Request

{
	"title": "CTO"
}

// Response

{
	"data": {
		"id": "b917be29-e326-4597-ad73-ff892be35aac",
		"first_name": null,
		"last_name": null,
		"email": "another@example.com",
		"password": "**********",
		"location": null,
		"title": "CTO",
		"description": null,
		"tags": null,
		"avatar": null,
		"language": "en-US",
		"theme": "auto",
		"tfa_secret": null,
		"status": "active",
		"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
		"token": null,
		"last_access": null,
		"last_page": null
	}
}

---

Delete a User

Delete an existing user.

Returns

Empty body.

DELETE /users/:id

// Empty Response

---

Delete Multiple Users

Delete multiple existing users.

Request Body

An array of user primary keys

Returns

Empty body.

DELETE /users

// Request
["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]

// Empty Response

---

Invite a new User

Invite a new user by email.

Request Body

email Required
User email to invite.

role Required
Role of the new user.

invite_url
Provide a custom invite url which the link in the email will lead to. The invite token will be passed as a parameter.

Returns

Empty body.

POST /users/invite

// Request

{
	"email": "another@example.com",
	"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
}

// Empty Response

---

Accept User Invite

Accept your invite. The invite user endpoint sends the email a link to the Admin App.

This link includes a token, which is then used to activate the invited user.

Request Body

token Required
Accept invite token.

password Required
Password for the user.

Returns

Empty body.

POST /users/invite/accept

// Request

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

// Empty Response

---

Enable Two-Factor Authentication

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

Request Body

password Required
The user's password.

Returns

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/enable

// Request
{
	"password": "d1r3ctu5"
}

// Response

{
	"data": {
		"secret": "PUITSOZFEEPXABIG",
		"otpauth_url": "otpauth://totp/Directus:null%20null?secret=PUITSOZFEEPXABIG&period=30&digits=6&algorithm=SHA1&issuer=Directus"
	}
}

---

Disable Two-Factor Authentication

Disables two-factor authentication by removing the OTP secret from the user.

Request Body

otp Required
One-time password generated by the authenticator app.

Returns

Empty response.

POST /users/me/tfa/disable

// Request
{
	"otp": "859014"
}

// Empty Response