docs/api/apiv3/tags/users.yml
---
description: |-
## Actions
| Link | Description | Condition |
|:-------------------:| -------------------------------------------------------------------- | ---------------------------------------------------------------- |
| lock | Restrict the user from logging in and performing any actions | not locked; **Permission**: Administrator |
| show | Link to the OpenProject user page (HTML) | |
| unlock | Allow a locked user to login and act again | locked; **Permission**: Administrator |
| updateImmediately | Updates the user's attributes. | **Permission**: Administrator, manage_user global permission |
| delete | Permanently remove a user from the instance | **Permission**: Administrator, self-delete |
## Linked Properties
| Link | Description | Type | Constraints | Supported operations | Condition |
|:-----------:|-------------------------------------------------------------- | ------------- | --------------------- | -------------------- | ----------------------------------------- |
| self | This user | User | not null | READ | |
| auth_source | Link to the user's auth source (endpoint not yet implemented) | LdapAuthSource | | READ / WRITE | **Permission**: Administrator |
| members | Link to collection of all the user's memberships. The list will only include the memberships in projects in which the requesting user has the necessary permissions. | MemberCollection | | READ | **Permission**: view members or manage members in any project |
Depending on custom fields defined for users, additional links might exist.
## Local Properties
| Property | Description | Type | Constraints | Supported operations | Condition |
| :----------: | --------------------------------------------------------- | -------- | ---------------------------------------------------- | -------------------- | ----------------------------------------------------------- |
| id | User's id | Integer | x > 0 | READ | |
| login | User's login name | String | unique, 256 max length | READ / WRITE | **Permission**: Administrator, manage_user global permission |
| firstName | User's first name | String | 30 max length | READ / WRITE | **Permission**: Administrator, manage_user global permission |
| lastName | User's last name | String | 30 max length | READ / WRITE | **Permission**: Administrator, manage_user global permission |
| name | User's full name, formatting depends on instance settings | String | | READ | |
| email | User's email address | String | unique, 60 max length | READ / WRITE | E-Mail address not hidden, **Permission**: Administrator, manage_user global permission |
| admin | Flag indicating whether or not the user is an admin | Boolean | in: [true, false] | READ / WRITE | **Permission**: Administrator |
| avatar | URL to user's avatar | Url | | READ | |
| status | The current activation status of the user (see below) | String | in: ["active", "registered", "locked", "invited"] | READ | |
| language | User's language | String | ISO 639-1 | READ / WRITE | **Permission**: Administrator, manage_user global permission |
| password | User's password for the default password authentication | String | | WRITE | **Permission**: Administrator |
| identity_url | User's identity_url for OmniAuth authentication | String | | READ / WRITE | **Permission**: Administrator |
| createdAt | Time of creation | DateTime | | READ | |
| updatedAt | Time of the most recent change to the user | DateTime | | READ | |
Depending on custom fields defined for users, additional properties might exist.
The `status` of a user can be one of:
* `active` - the user can log in with the account right away
* `invited` - the user is invited and is pending registration
If the user's `status` is set to `active` during creation a means of authentication
has to be provided which is one of the following:
* `password` - The password with which the user logs in.
* `auth_source` - Link to an LDAP auth source.
* `identity_url` - The identity URL of an OmniAuth authentication provider.
If all of these are missing the creation will fail with an "missing password" error.
The `language` is limited to those activated in the system.
Due to data privacy, the user's properties are limited to reveal as little about the user as possible.
Thus `login`, `firstName`, `lastName`, `language`, `createdAt` and `updatedAt` are hidden for all
users except for admins or the user themselves.
Please note that custom fields are not yet supported by the api although the backend supports them.
name: Users