User management

These endpoints list, create, update, and delete users, change their passwords, set installation admin status, and create service accounts.

Permissions

• Each endpoint requires an admin or users-manage grant of any scope. List users requires one that is not scoped to tenants.
• Update, delete, and change password also require strictly more authority than the target user, who must belong only to tenants that your grant reaches. Otherwise the answer is 403 CAPABILITY_UNAUTHORIZED.
• Get user details requires only that the user belongs to tenants that your grant reaches.

See Tenants for who can act on whom.

Users

List users

GET /api/v1/users

Returns users, with cursor-based pagination and filters.

Response:

{
  "users": [
    {
      "id": "f30ed1f9-be44-46a3-9050-03e9561e94f0",
      "name": "John Doe",
      "email": "john@example.com",
      "admin_rights": { "is_instance_admin": false, "is_tenant_admin": false },
      "type": "user",
      "auth_origin": "local",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total_count": 10,
  "limit": 25,
  "has_more": false,
  "next_cursor": null
}

Get user details

GET /api/v1/users/detail?user_id={user_id}

Returns the details of one user.

Response:

{
  "id": "f30ed1f9-be44-46a3-9050-03e9561e94f0",
  "name": "John Doe",
  "email": "john@example.com",
  "admin_rights": { "is_instance_admin": false, "is_tenant_admin": false },
  "type": "user",
  "created_at": "2024-01-15T10:30:00Z"
}

The response also includes auth_origin (how the user authenticates) and avatar_url when they are set.

Create user

POST /api/v1/users

Creates a user account.

Request body:

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "password": "secure-password",
  "is_instance_admin": false
}

Response: 201 Created

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "is_instance_admin": false
}

The new user joins each of your tenants that your grant reaches. If it reaches none, the answer is 403. Setting is_instance_admin requires an installation-wide admin grant.

Update user

PUT /api/v1/users/update?user_id={user_id}

Updates a user.

Request body:

{
  "name": "Jane Smith",
  "email": "jane.smith@example.com"
}

Response: 200 OK with the updated user object, with the same admin_rights object as the users list and the user details.

is_instance_admin: false on the last installation admin returns 400 CANNOT_REMOVE_LAST_ADMIN and discards the whole update. name, email, and avatar_url are written in the same transaction, so none of them is saved.

Delete user

DELETE /api/v1/users/delete?user_id={user_id}

Soft-deletes a user: marks the user as deleted and invalidates their API keys.

Response:

{
  "id": "f30ed1f9-be44-46a3-9050-03e9561e94f0",
  "deleted": true
}

Errors:

• 403 when the target holds as much authority as you or more, or belongs to a tenant that your grant does not reach. Instance admins are exempt and can delete each other.
• A users-manage holder cannot delete an admin or another users-manage holder.
• 400 CANNOT_DELETE_LAST_ADMIN for the last instance admin.
• 400 CANNOT_DELETE_OWN_ACCOUNT for your own account.

Change user password

POST /api/v1/users/change-password?user_id={user_id}

Changes the password of a user.

Request body:

{
  "new_password": "new-secure-password",
  "current_password": "old-password"
}

Response:

{
  "id": "f30ed1f9-be44-46a3-9050-03e9561e94f0",
  "password_changed": true
}

Another user's password requires no current_password. Instance admins are exempt from the authority comparison in Permissions, and can reset each other's passwords.

Set installation admin status

POST /api/v1/users/set-instance-admin?user_id={user_id}

Sets the installation-wide admin capability of the user to the requested value:

• true writes an unrestricted admin capability, and replaces any tenants allow-list that the user held.
• false removes an unrestricted admin capability and leaves a tenant-scoped one untouched. On a user who never held the installation-wide grant, it changes nothing.

Request body:

{
  "is_instance_admin": true
}

Response:

{
  "id": "f30ed1f9-be44-46a3-9050-03e9561e94f0",
  "is_instance_admin": true
}

The value is set, not toggled: the server never reads the current grant to invert it, so a repeated call changes nothing. Removing the grant from the last installation admin returns 400 CANNOT_REMOVE_LAST_ADMIN, and removing your own returns 400 CANNOT_ACT_ON_SELF, whoever else holds one.

Service accounts

Create service account

POST /api/v1/api-users

Creates a service account (API user) for programmatic access.

Request body:

{
  "name": "ci-production",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response:

{
  "user_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

The response shows the token only one time. Save it immediately.