Users API

9 endpoints. Request and response schemas are described on the schemas page; the other tags are listed in the API index.

Endpoints

GET /api/v1/users

List users

List all users (admin only)

Parameters

Name	In	Type	Required	Description
page	query	integer	no	Minimum: 1.
per_page	query	integer	no	Minimum: 1. Maximum: 100.
q	query	string	no	Search query

Responses

Status	Description	Body
200	List of users	application/json: object
400	Invalid request	application/json: Error
403	Admin access required	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
data	array of User	no	-
page	integer	no	-
per_page	integer	no	-
total	integer	no	-

POST /api/v1/users

Create user

Create a new user (admin only)

Request body (required)

application/json: object

Field	Type	Required	Description
disabled	boolean	no	-
email	string (email)	no	-
full_name	string	no	-
must_change_password	boolean	no	-
password	string	no	-
username	string	yes	-

Responses

Status	Description	Body
201	User created	application/json: User
400	Invalid request	application/json: Error
403	Admin access required	-
409	Conflict with the current state	application/json: Error

GET /api/v1/users/{id}

Get user

Get details of a specific user (admin only)

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	-

Responses

Status	Description	Body
200	User details	application/json: User
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	User not found	-

PATCH /api/v1/users/{id}

Update user

Update a user (admin only). Setting disabled: true keeps the account, blocks login and revokes its sessions and project tokens; disabled: false re-enables it.

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	-

Request body (required)

application/json: object

Field	Type	Required	Description
disabled	boolean	no	-
email	string (email)	no	-
full_name	string	no	-
must_change_password	boolean	no	-
password	string	no	-

Responses

Status	Description	Body
200	User updated	application/json: User
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	User not found	-

DELETE /api/v1/users/{id}

Delete user

Permanently delete a user (admin only). The account row, its API tokens, sessions, project memberships, group links, permission assignments and SSO link are removed; creator/owner references on other objects are cleared. Refused for your own account (400) and for the last enabled admin (409). To keep the account, set disabled with PATCH instead. A later SSO login with the same external ID provisions a fresh user.

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	-

Responses

Status	Description	Body
204	User deleted	-
400	Cannot delete your own account	-
403	Forbidden	application/json: Error
404	User not found	-
409	Cannot delete the last enabled admin	-

GET /api/v1/users/{id}/groups

List user's groups

List groups that a user belongs to

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	-

Responses

Status	Description	Body
200	List of groups	application/json: object
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	User not found	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
data	array of Group	no	-

GET /api/v1/users/{id}/tokens

List user's tokens

List the active (not revoked) API tokens of a user (owner or admin)

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	-

Responses

Status	Description	Body
200	List of tokens	application/json: object
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	User not found	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
data	array of Token	no	-

POST /api/v1/users/{id}/tokens

Create token for user

Create an API token for a user (admin only)

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	-

Request body (required)

application/json: object

Field	Type	Required	Description
expires_at	string (date-time)	no	-
kind	string	yes	One of: access, deploy.
name	string	yes	-
scopes	array of string	no	-

Responses

Status	Description	Body
201	Token created	application/json: TokenCreateResponse
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	The addressed resource was not found	application/json: Error

DELETE /api/v1/users/{id}/tokens/{tokenId}

Revoke user's token

Revoke an API token for a user (admin only)

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	-
tokenId	path	string (uuid)	yes	-

Responses

Status	Description	Body
204	Token revoked	-
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	Token not found	-