60df20d780
* Simplified generics and imports for items page snippets * Simplified generics and imports for files page snippets * Fixing simplified generic snippets in items page * Simplified generics and imports for activity page snippets * Simplified generics and imports for collections page snippets * Simplified generics and imports for dashboards page snippets * Simplified generics and imports for extensions page snippets * Simplified generics and imports for fields page snippets * Simplified generics and imports for flows page snippets * Simplified generics and imports for folders page snippets * Simplified generics and imports for notifications page snippets * Simplified generics and imports for operations page snippets * Simplified generics and imports for panels page snippets * Simplified generics and imports for permissions page snippets * Simplified generics and imports for presets page snippets * Simplified generics and imports for relations page snippets * Simplified generics and imports for relations page snippets * Simplified generics and imports for revisions page snippets * Simplified generics and imports for roles page snippets * Consolidated imports for schema page snippets * Simplified generics and imports for server page snippets * Simplified generics and imports for settings page snippets * Fixed mixed up snippets and simplified generics and imports for shares page snippets * Simplified generics and imports for translation page snippets * Fixed mixed up snippets and simplified generics and imports for user page snippets * Simplified generics and imports fo uutilitie pages snippets * Simplified generics and imports for webhook pages snippets * Simplified generics and imports for authentication pages snippets * Consolidated imports for query pages sdk snippets * Format files * Update lockfile * Fix spelling * Format snippets * Aling `result` const * Small clean-ups - Align `SEARCH` snippets, move "Learn more..." next to other hint - ids -> IDs - Other alignments --------- Co-authored-by: Bevis Halsey-Perry <hi@be7.is> Co-authored-by: Pascal Jufer <pascal-jufer@bluewin.ch>
26 KiB
description, readTime, pageClass
| description | readTime | pageClass |
|---|---|---|
| REST and GraphQL API documentation on the Users collection in Directus. | 9 min read | 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.
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 array
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 secret key for it.
status string
Status of the user. One of draft, invited, active, suspended, archived.
role uuid
Role of the user. Many-to-one to roles.
token string
Static access token for the user.
last_access date
Last time the user accessed the API.
last_page string
Last page in the app the user used.
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 json
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.
{
"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.
Request
GET /users
SEARCH /users
If using SEARCH you can provide a query object as the body of your request.
POST /graphql/system
type Query {
users: [directus_users]
}
import { createDirectus, rest, readUsers } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readUsers(query_object));
Query Parameters
Supports all global query parameters.
Response
An array of up to limit user objects. If no items are available, data will be an empty array.
Example
GET /users
SEARCH /users
query {
users {
first_name
last_name
email
}
}
import { createDirectus, rest, readUsers } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
readUsers({
fields: ['*'],
})
);
Retrieve a User
List an existing user by primary key.
Request
GET /users/:id
POST /graphql/system
type Query {
users_by_id(id: ID!): directus_users
}
import { createDirectus, rest, readUser } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readUser(user_id, query_object));
Query Parameters
Supports all global query parameters.
Response
Returns the requested user object.
Example
GET /users/72a1ce24-4748-47de-a05f-ce9af3033727
POST /graphql/system
query {
users_by_id(id: "72a1ce24-4748-47de-a05f-ce9af3033727") {
first_name
last_name
email
}
}
import { createDirectus, rest, readUser } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
readUser('0513b6e8-55f2-4ff5-906c-f1a29d7b983c', {
fields: ['*'],
})
);
Retrieve the Current User
Retrieve the currently authenticated user.
Request
GET /users/me
POST /graphql/system
type Query {
users_me: directus_users
}
import { createDirectus, rest, readMe } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readMe(query_object));
Query Parameters
Supports all global query parameters.
Response
Returns the user object for the currently authenticated user.
Example
GET /users/me
query {
users_me {
email
}
}
import { createDirectus, rest, readMe } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
readMe({
fields: ['*'],
})
);
Update the Current User
Update the authenticated user.
Request
PATCH /users/me
Provide a partial user object as the body of your request.
POST /graphql/system
type Mutation {
update_users_me(data: update_directus_users_input!): directus_users
}
import { createDirectus, rest, updateMe } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateMe(partial_user_object));
Query Parameters
Supports all global query parameters.
Response
Returns the updated user object for the authenticated user.
Example
PATCH /users/me
{
"email": "new.email@example.com"
}
POST /graphql/system
mutation {
update_users_me(data: { email: "new.email@example.com" }) {
email
}
}
import { createDirectus, rest, updateMe } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
updateMe({
email_notifications: false,
})
);
Create a User
Create a new user
Request
POST /users
Provide a user object as the body of your request.
POST /graphql/system
type Mutation {
create_users_item(data: create_directus_users_input!): directus_users
}
import { createDirectus, rest, createUser } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(createUser(user_object));
Query Parameters
Supports all global query parameters.
Request Body
A partial user object.
email and password are required to authenticate with the default authentication provider.
Response
Returns the user object for the created user.
Example
POST /users
{
"email": "another@example.com",
"password": "d1r3ctu5",
"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
}
POST /graphql/system
mutation {
create_users_item(
data: {
email: "another@example.com"
password: "d1r3ctu5"
role: { id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", name: "Public", admin_access: false, enforce_tfa: false }
}
) {
email
role
}
}
::: tip
Please note that if you include the Role in the create_users_items call it will be treated as an Upsert and not only
as adding a relationship. So make sure the ID exists, and the other parameters match the existing role, otherwise it
could be modified by the user call.
:::
import { createDirectus, rest, createUser } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
createUser({
email: 'hi@email.com',
password: 'qwerty123',
})
);
Create Multiple Users
Create multiple new users
Request
POST /users
Provide an array of user objects as the body of your request.
POST /graphql/system
type Mutation {
create_users_items(data: [create_directus_users_input!]!): [directus_users]
}
import { createDirectus, rest, createUsers } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(createUsers(user_object_array));
Query Parameters
Supports all global query parameters.
Request Body
An array of partial user objects.
email and password are required.
Response
Returns the user objects for the created users.
Example
POST /users
[
{
"email": "admin@example.com",
"password": "p455w0rd",
"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
},
{
"email": "another@example.com",
"password": "d1r3ctu5",
"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
}
]
POST /graphql/system
mutation {
create_users_items(
data: [
{
email: "admin@example.com"
password: "p455w0rd"
role: { id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", name: "Public", admin_access: false, enforce_tfa: false }
}
{
email: "another@example.com"
password: "d1r3ctu5"
role: { id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", name: "Public", admin_access: false, enforce_tfa: false }
}
]
) {
email
role
}
}
::: tip
Please note that if you include the Role in the create_users_items call it will be treated as an Upsert and not only
as adding a relationship. So make sure the ID exists, and the other parameters match the existing role, otherwise it
could be modified by the user call.
:::
import { createDirectus, rest, createUsers } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
createUsers([
{
email: 'hello@email.com',
password: 'qwerty123',
},
{
email: 'person@email.com',
password: 'QwErTy1994',
},
])
);
Update a User
Update an existing user.
Request
PATCH /users/:id
Provide a partial user object as the body of your request.
POST /graphql/system
type Mutation {
update_users_item(id: ID!, data: update_directus_users_input!): directus_users
}
import { createDirectus, rest, updateUser } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateUser(user_id, partial_user_object));
Query Parameters
Supports all global query parameters.
Request Body
A partial user object.
Response
Returns the user object for the updated user.
Example
PATCH /users/72a1ce24-4748-47de-a05f-ce9af3033727
{
"title": "CTO"
}
POST /graphql/system
mutation {
update_users_item(id: "72a1ce24-4748-47de-a05f-ce9af3033727", data: { title: "CTO" }) {
first_name
last_name
}
}
import { createDirectus, rest, updateUser } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
updateUser('e41605bd-f9bc-4c9c-b09d-3ccb7b137fbb', {
email_notifications: false,
})
);
Update Multiple Users
Update multiple existing users.
Request
PATCH /users
{
"keys": user_id_array,
"data": partial_user_object
}
POST /graphql/system
type Mutation {
update_users_items(ids: [ID!]!, data: update_directus_users_input!): [directus_users]
}
import { createDirectus, rest, updateUsers } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateUsers(user_id_array, partial_user_object));
Query Parameters
Supports all global query parameters.
Request Body
keys Required
Array of primary keys of the users you'd like to update.
data Required
Any of the user object's properties.
Response
Returns the user objects for the updated users.
Example
PATCH /users
{
"keys": ["72a1ce24-4748-47de-a05f-ce9af3033727", "9c3d75a8-7a5f-41a4-be0a-1488fd974511"],
"data": {
"title": "CTO"
}
}
POST /graphql/system
mutation {
update_users_items(
ids: ["72a1ce24-4748-47de-a05f-ce9af3033727", "9c3d75a8-7a5f-41a4-be0a-1488fd974511"]
data: { title: "CTO" }
) {
first_name
last_name
}
}
import { createDirectus, rest, updateUsers } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
updateUsers(['e41605bd-f9bc-4c9c-b09d-3ccb7b137fbb', '5ec6ee0a-62ad-460d-a91e-fed63e3d804c'], {
email_notifications: false,
})
);
Delete a User
Delete an existing user.
Request
DELETE /users/:id
POST /graphql/system
type Mutation {
delete_users_item(id: ID!): delete_one
}
import { createDirectus, rest, deleteUser } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(deleteUser(user_id));
Response
Empty body.
Example
DELETE /users/72a1ce24-4748-47de-a05f-ce9af3033727
POST /graphql/system
mutation {
delete_users_item(id: "72a1ce24-4748-47de-a05f-ce9af3033727") {
id
}
}
import { createDirectus, rest, deleteUser } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(deleteUser('965749ad-e5e4-4e38-aa91-25a252b8ccd9'));
Delete Multiple Users
Delete multiple existing users.
Request
DELETE /users
Provide an array of user IDs as the body of your request.
POST /graphql/system
type Mutation {
delete_users_items(ids: [ID!]!): delete_many
}
import { createDirectus, rest, deleteUsers } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(deleteUsers(user_id_array));
Request Body
An array of user primary keys
Response
Empty body.
Example
DELETE /users
["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]
mutation {
delete_users_items(ids: ["72a1ce24-4748-47de-a05f-ce9af3033727", "9c3d75a8-7a5f-41a4-be0a-1488fd974511"]) {
ids
}
}
import { createDirectus, rest, deleteUsers } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
deleteUsers(['e41605bd-f9bc-4c9c-b09d-3ccb7b137fbb', '5ec6ee0a-62ad-460d-a91e-fed63e3d804c'])
);
Invite a new User
Invite a new user by email.
Request
POST /users/invite
{
"email": invited_user_email,
"role": invited_user_role
}
POST /graphql/system
type Mutation {
users_invite(email: String!, role: String!, invite_url: String): Boolean
}
import { createDirectus, rest, inviteUser } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(inviteUser(invited_user_email, invited_user_role));
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.
Note: You need to configure the
USER_INVITE_URL_ALLOW_LIST environment variable to enable this feature.
Response
Empty body.
Example
POST /users/invite
{
"email": "another@example.com",
"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
}
POST /graphql/system
mutation {
users_invite(email: "another@example.com", role: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7")
}
import { createDirectus, rest, inviteUser } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(inviteUser('another@example.com', 'c86c2761-65d3-43c3-897f-6f74ad6a5bd7'));
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
POST /users/invisponse/accept
{
"token": invite_token,
"password": user_password
}
POST /graphql/system
type Mutation {
users_invite_accept(token: String!, password: String!): Boolean
}
import { createDirectus, rest, acceptUserInvite } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(acceptUserInvite(invite_token, user_password));
Request Body
token Required
Accept invite token.
password Required
Password for the user.
Response
Empty body.
Example
POST /users/invite/accept
{
"token": "eyJh...KmUk",
"password": "d1r3ctu5"
}
mutation {
users_invite_accept(token: "eyJh...KmUk", password: "d1r3ctu5")
}
import { createDirectus, rest, acceptUserInvite } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(acceptUserInvite('eyJh...KmUk', 'd1r3ctu5'));
Generate Two-Factor Authentication Secret
Generates a secret and returns the URL to be used in an authenticator app.
Request
POST /users/me/tfa/generate
{
"password": user_password
}
POST /graphql/system
type Mutation {
users_me_tfa_generate(password: String!): users_me_tfa_generate_data
}
import { createDirectus, rest, generateTwoFactorSecret } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(generateTwoFactorSecret(user_password));
Request Body
password Required
The user's password.
Response
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.
Example
POST /users/me/tfa/generate
{
"password": "d1r3ctu5"
}
POST /graphql/system
mutation {
users_me_tfa_generate(password: "d1r3ctu5") {
secret
otpauth_url
}
}
import { createDirectus, rest, generateTwoFactorSecret } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(generateTwoFactorSecret('d1r3ctu5'));
Enable Two-Factor Authentication
Adds a TFA secret to the user account.
Request
POST /users/me/tfa/enable
{
"otp": one_time_password,
"secret": two_factor_authorization_secret
}
POST /graphql/system
type Mutation {
users_me_tfa_enable(otp: String!, secret: String!): Boolean
}
import { createDirectus, rest, enableTwoFactor } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(enableTwoFactor(secret, otp));
Request Body
secret Required
The TFA secret from tfa/generate.
otp Required
OTP generated with the secret, to recheck if the user has a correct TFA setup
Response
Empty response.
Example
POST /users/me/tfa/enable
{
"otp": "123456",
"secret": "3CtiutsNBmY3szHE"
}
POST /graphql/system
mutation {
users_me_tfa_enable(otp: "123456", secret: "3CtiutsNBmY3szHE")
}
import { createDirectus, rest, enableTwoFactor } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(enableTwoFactor('123456', '3CtiutsNBmY3szHE'));
Disable Two-Factor Authentication
Disables two-factor authentication by removing the OTP secret from the user.
Request
POST /users/me/tfa/disable
{
"otp": one_time_password
}
POST /graphql/system
type Mutation {
users_me_tfa_disable(otp: String!): Boolean
}
import { createDirectus, rest, disableTwoFactor } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(disableTwoFactor(otp));
Request Body
otp Required
One-time password generated by the authenticator app.
Response
Empty response.
Example
POST /users/me/tfa/disable
{
"otp": "859014"
}
POST /graphql/system
mutation {
users_me_tfa_disable(otp: "591763")
}
import { createDirectus, rest, disableTwoFactor } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(disableTwoFactor('591763'));