content/guides/03.auth/3.creating-users.md
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.
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": "[email protected]",
"password": "d1r3ctu5"
}
::callout{icon="material-symbols:info-outline"}
Regardless of whether the registration was successful or not, the Directus API will always respond with an empty 204 response.
This is to mitigate potentially leaking the identity of registered users. ::
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.
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 registration email will use this URL, appending a verification token in the URL as a token parameter.
Your application must extract this value and send a GET request to the verify email endpoint, with the token appended as a token parameter.
GET /users/register/verify-email?token=<token>
::callout{icon="material-symbols:menu-book-outline" color="primary" to="/configuration/security-limits"}
The USER_REGISTER_URL_ALLOW_LIST environment variable must be configured.
::
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": "[email protected]",
"password": "d1r3ctu5",
"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
}
::callout{icon="material-symbols:code-blocks-rounded" color="green" to="/api/users"} See all parameters and payload options for the create user endpoint. ::
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": "[email protected]",
"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
}
::callout{icon="material-symbols:menu-book-outline" color="primary" to="/configuration/email"} An email service must be configured to send 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"
}
::callout{icon="material-symbols:menu-book-outline" color="primary" to="/configuration/security-limits"}
The USER_INVITE_URL_ALLOW_LIST environment variable must be configured.
::