github/directus
1
0
Fork 0
mirror of https://github.com/directus/directus.git synced 2026-01-26 03:38:09 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
54b16fdfd58addbf22b25b60fbc219cc7bef9f19
directus/docs/reference/api/rest/users.md
Ben Haynes 239c021f12 Updates to API Reference
2021-02-08 17:31:07 -05:00

665 lines
9.6 KiB
Markdown
Raw Blame History

---
pageClass: page-reference
---
# Users
<div class="two-up">
<div class="left">
> 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](/concepts/users/).
</div>
<div class="right">
[[toc]]
</div>
</div>
---
## The User Object
<div class="two-up">
<div class="left">
<div class="definitions">
`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](/reference/api/rest/files/).
`language` **string**\
Language the Admin App is rendered in. See [our Crowdin page](https://locales.directus.io) for all available languages and
translations.
`theme` **string**\
One of `auto`, `light`, `dark`.
`tfa_secret` **string**\
When TFA is enabled, this holds the
</div>
</div>
<div class="right">
```json
{
"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"
}
```
</div>
</div>
---
## List Users
List all users that exist in Directus.
<div class="two-up">
<div class="left">
### Query Parameters
Supports all [global query parameters](/reference/api/query).
### Returns
An array of up to [limit](/reference/api/query/#limit) [user objects](#the-user-object). If no items are available, data
will be an empty array.
</div>
<div class="right">
```
GET /users
```
```json
// 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"
},
{...},
{...}
]
}
```
</div>
</div>
---
## Retrieve a User
List an existing user by primary key.
<div class="two-up">
<div class="left">
### Query Parameters
Supports all [global query parameters](/reference/api/query).
### Returns
Returns the requested [user object](#the-user-object).
</div>
<div class="right">
```
GET /users/:id
```
```json
// 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"
}
}
```
</div>
</div>
---
## Retrieve the Current User
Retrieve the currently authenticated user.
<div class="two-up">
<div class="left">
### Query Parameters
Supports all [global query parameters](/reference/api/query).
### Returns
Returns the [user object](#the-user-object) for the currently authenticated user.
</div>
<div class="right">
```
GET /users/me
```
```json
// 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"
}
}
```
</div>
</div>
---
## Create a User
Create one or more new user(s).
<div class="two-up">
<div class="left">
### Query Parameters
Supports all [global query parameters](/reference/api/query).
### Request Body
A partial [user object](#the-user-object) or an array of partial [user objects](#the-user-object).
`email` and `password` are required.
### Returns
Returns the [user object(s)](#the-user-object) for the created user(s).
</div>
<div class="right">
```
POST /users
```
```json
// Request
{
"email": "another@example.com",
"password": "d1r3ctu5",
"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
}
```
```json
// 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
}
}
```
</div>
</div>
---
## Update a User
Update an existing user.
<div class="two-up">
<div class="left">
### Query Parameters
Supports all [global query parameters](/reference/api/query).
### Request Body
A partial [user object](#the-user-object).
### Returns
Returns the [user object](#the-user-object) for the created user.
</div>
<div class="right">
```
PATCH /users/:id
```
```json
// Request
{
"title": "CTO"
}
```
```json
// 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
}
}
```
</div>
</div>
---
## Delete a User
Delete an existing user.
<div class="two-up">
<div class="left">
### Returns
Empty body.
</div>
<div class="right">
```
DELETE /users/:id
```
```json
// Empty Response
```
</div>
</div>
---
## Delete Multiple Users
Delete multiple existing users.
<div class="two-up">
<div class="left">
### Request Body
An array of user primary keys
### Returns
Empty body.
</div>
<div class="right">
```
DELETE /users
```
```json
// Request
["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]
```
```json
// Empty Response
```
</div>
</div>
---
## Invite a new User
Invite a new user by email.
<div class="two-up">
<div class="left">
### Request Body
<div class="definitions">
`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.
</div>
### Returns
Empty body.
</div>
<div class="right">
```
POST /users/invite
```
```json
// Request
{
"email": "another@example.com",
"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
}
```
```json
// Empty Response
```
</div>
</div>
---
## Accept User Invite
Accept your invite. The [invite user endpoint](#invite-a-new-user) sends the email a link to the Admin App.
This link includes a token, which is then used to activate the invited user.
<div class="two-up">
<div class="left">
### Request Body
<div class="definitions">
`token` **Required**\
Accept invite token.
`password` **Required**\
Password for the user.
</div>
### Returns
Empty body.
</div>
<div class="right">
```
POST /users/invite/accept
```
```json
// Request
{
"token": "eyJh...KmUk",
"password": "d1r3ctu5"
}
```
```json
// Empty Response
```
</div>
</div>
---
## Enable Two-Factor Authentication
Generates a secret and returns the URL to be used in an authenticator app.
<div class="two-up">
<div class="left">
### Request Body
<div class="definitions">
`password` **Required**\
The user's password.
</div>
### Returns
<div class="definitions">
`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.
</div>
</div>
<div class="right">
```
POST /users/me/tfa/enable
```
```json
// Request
{
"password": "d1r3ctu5"
}
```
```json
// Response
{
"data": {
"secret": "PUITSOZFEEPXABIG",
"otpauth_url": "otpauth://totp/Directus:null%20null?secret=PUITSOZFEEPXABIG&period=30&digits=6&algorithm=SHA1&issuer=Directus"
}
}
```
</div>
</div>
---
## Disable Two-Factor Authentication
Disables two-factor authentication by removing the OTP secret from the user.
<div class="two-up">
<div class="left">
### Request Body
<div class="definitions">
`otp` **Required**\
One-time password generated by the authenticator app.
</div>
### Returns
Empty response.
</div>
<div class="right">
```
POST /users/me/tfa/disable
```
```json
// Request
{
"otp": "859014"
}
```
```json
// Empty Response
```
</div>
</div>
Reference in New Issue View Git Blame Copy Permalink