mirror of
https://github.com/directus/directus.git
synced 2026-02-04 11:05:14 -05:00
817ccf3620
* Add Quickstart Guide * Update installation * Remove unused files * Update support/backing * Tweaks in concepts * Setup file structure for API reference 2.0 * Setup page layout for reference * Add clean-urls plugin * getting started updates * Finish authentication rest * getting started updates * Render stylus in 2 spaces * Various * Various * Finish activity docs * Add collections reference * Add extension reference * concepts updates * Fields/tweaks * Add files doc * Add revisions * concepts docs * More api reference * Finish rest api reference (finally) * initial concepts * More things * Add assets api ref * Move sections from file to assets * Add environment variables * contributing docs * Add field transforms page * Left align table headers * concept links * Add API config * Fix mobile nav * Add migrating a project * doc link fixes Co-authored-by: Ben Haynes <ben@rngr.org>
640 lines
9.3 KiB
Markdown
640 lines
9.3 KiB
Markdown
---
|
|
pageClass: page-reference
|
|
---
|
|
|
|
# Users
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
Groups of users that share permissions.
|
|
|
|
</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.
|
|
|
|
</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>
|