Creating Users

A user is an item in the directus_users collection. There are no required fields by default, although you may choose to require values for any system or user-created fields.

To log in with an email and password they must be set on the user item. A user can also have a role and any number of policies that can be assigned in the user detail page.

There are three ways to create new users in Directus - registration, creation, and invitation.

Register a User

The user registration feature is disabled by default. To make use of it, it must first be enabled via project settings. By enabling user registration, it is open to anyone via the Data Studio or via API. Once enabled, all users who register will receive the role configured in project settings.

The Register a User endpoint also only supports first_name and last_name fields to be set.

{
  "email": "hello@example.com",
  "password": "d1r3ctu5"
}

Email Verification & Validation

If enabled in project settings, newly-registered users will receive the Unverified status and will be unable to log in until they click the verification link sent via email.

You may also create custom email filter rules to ensure the registering user's email matches certain patterns or has certain characteristics. All string filters are available.

Seamless Registration

You can use the verification system within your own application ensuring users do not need to access the Data Studio.

When using the register user endpoint, add a verification_url property. The invite email will use this URL instead of your Directus project, appending the invite token in the URL as a token parameter.

Your application must extract this value and send it to the verify email endpoint.

{
  "token": "eyJh...KmUk"
}

Create a New User

The Users API can also create a new user. Any field in the directus_users collection can be set when creating a user, but the correct public collection permissions will be required.

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

Inviting Users

Inviting a user will send an email with an invite URL. Once invited, the user will be created with the provided email address and a status of invited. When a user accepts their invite they must provide a password and will be able to log in.

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

Seamless Invites

You can use the invite system within your own application ensuring users do not need to access the Data Studio.

When using the invite user endpoint, add an invite_url property. The invite email will use this URL instead of your Directus project, appending the invite token in the URL as a token parameter.

Your application must extract this value, collect the new user's password, and send both to the accept invite endpoint.

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