Reference
Users
Admin API endpoints for listing, reading, changing, suspending and removing users and resending invitations.
Endpoints under https://acme.sovrain.net/api/v1/users. Authentication, conventions and the error format are on
Admin API. New users are created with Invitations.
The user object
Returned by GET /users/{id} and by every write that answers 200.
{
"id": "FomjVqEuLmL5CBPAfVwYK2",
"login": "anna@acme.example",
"email": "anna@acme.example",
"display_name": "Anna Nowak",
"first_name": "Anna",
"last_name": "Nowak",
"status": "active",
"suspended": false,
"groups": [
{ "id": "gtEPGF6QcVzZ7nhfkqdwQ8", "name": "All" },
{ "id": "SuT8oWQLVMPzwYQyhKjm32", "name": "Engineering" }
],
"attributes": { "department": "R&D" },
"created_at": "2026-11-17T09:30:00.900848643Z"
}
| Field | Type | Notes |
|---|---|---|
id | string | Public id. The same value is the OpenID Connect sub and the externalId attribute. |
login | string | Login name. For people invited by email it is the address as it was typed. |
email | string or null | The address as it was typed. Whether it is verified is not returned. |
display_name | string or null | The display name set on the profile |
first_name, last_name | string or null | |
status | string | invited (no password yet), suspended, or active |
suspended | boolean | |
groups | array | The groups the user is in, each {id, name}. Always includes All. |
attributes | object | Custom attribute values, key to string or null |
created_at | string |
Removed users are never returned.
List users
GET /api/v1/users
Scope: users:read
| Query parameter | Notes |
|---|---|
q | Matches part of the login, email, full name or “first last”, ignoring case |
status | active, invited or suspended. Any other value is ignored and returns everyone. |
limit | 1 to 200. Default 50. |
cursor | The next_cursor of the previous page, unchanged |
Users are returned in the order they were created.
Response 200:
{
"items": [
{
"id": "V3H7fPgwfvR2jqPjePvjHb",
"login": "jane",
"email": "jane@acme.example",
"display_name": null,
"status": "active",
"suspended": false,
"owner": true,
"admin": false,
"created_at": "2026-11-17T09:20:26.807755668Z"
}
],
"next_cursor": "YWZ0ZXI6MQ"
}
A list item has these fields instead of the full user object:
| Field | Notes |
|---|---|
display_name | The full name: the display name, else first and last name |
owner | Member of the built-in group Owners |
admin | Member of the built-in group Admins. An owner who is not in Admins shows false. |
Errors:
| Status | error | When |
|---|---|---|
| 400 | invalid_request | limit is not a number |
| 422 | refused | limit must be between 1 and 200, got 0; Invalid cursor: 'x'; pass back next_cursor unchanged |
Get a user
GET /api/v1/users/{id}
Scope: users:read
Response 200: the user object.
Errors:
| Status | error | When |
|---|---|---|
| 404 | not_found | Unknown user: external id 'x' |
Change the profile
PATCH /api/v1/users/{id}
Scope: users:write
| Field | Type | Required | Notes |
|---|---|---|---|
display_name | string | no | Left out: unchanged. Empty string: cleared. |
first_name | string | no | Same |
last_name | string | no | Same |
The login and the email cannot be changed through the API.
{ "display_name": "Anna Nowak", "first_name": "Anna", "last_name": "Nowak" }
Response 200: the user object.
Errors: 400 for an unknown field, 404 for an unknown user.
Replace attributes
PUT /api/v1/users/{id}/attributes
Scope: users:write
| Field | Type | Required | Notes |
|---|---|---|---|
attributes | object | yes | The complete set of custom attributes, key to string or null. Keys must exist in the organization’s attribute bank (compared ignoring case). {} removes every attribute. Empty keys are skipped. |
{ "attributes": { "department": "R&D", "costCenter": "4100" } }
Response 200: the user object.
Errors:
| Status | error | When |
|---|---|---|
| 422 | refused | Send 'attributes', the complete map; {} removes every attribute; Keys not in the attribute bank: department |
Attributes are added to the bank in the admin pages: Add custom attributes.
Replace group memberships
PUT /api/v1/users/{id}/groups
Scope: users:write
| Field | Type | Required | Notes |
|---|---|---|---|
groups | array of group ids | yes | The complete list. All is always kept. [] leaves only All. |
{ "groups": ["SuT8oWQLVMPzwYQyhKjm32"] }
Response 200: the user object.
- When callers change their own memberships, their memberships of Owners and Admins are kept, without an error.
- A user who leaves both Owners and Admins loses admin access, and that user’s Admin API grants are revoked.
- Joining a group can end delegations of that user, when the group is protected from delegation.
Errors:
| Status | error | When |
|---|---|---|
| 422 | refused | Send 'groups', the complete list of group ids; [] leaves only All; Unknown group in 'groups': 'x'; removing the last active owner from Owners |
To add or remove one membership, use PUT or DELETE /groups/{id}/members/{userId} on Groups.
Suspend a user
POST /api/v1/users/{id}/suspend
Scope: users:write
No body. Response 204.
Suspending blocks sign-in, ends the user’s sessions (with sign-out sent to connected applications), deletes the user’s password reset links, revokes the user’s Admin API grants and ends the user’s delegations.
Errors:
| Status | error | When |
|---|---|---|
| 422 | refused | You cannot suspend or remove the last owner of this organization. |
Restore a user
POST /api/v1/users/{id}/restore
Scope: users:write
No body. Response 204.
Restoring lifts the suspension. Revoked Admin API grants stay revoked.
Remove a user
DELETE /api/v1/users/{id}
Scope: users:delete
No body. Response 204.
Removal has the same effects as suspending, and the user disappears from every list. The user’s data stays in the organization’s database and in exports; removal cannot be undone through the API or the admin pages.
Errors:
| Status | error | When |
|---|---|---|
| 404 | not_found | Unknown or already removed user |
| 422 | refused | You cannot suspend or remove the last owner of this organization. |
Resend an invitation
POST /api/v1/users/{id}/invite
Scope: invites:write
No body. Sends the invitation email again to an invited user. Once the mail relay accepts the message, earlier invitation links of that user stop working.
Response 200:
{
"status": "sent",
"reason": null
}
| Field | Notes |
|---|---|
status | sent, failed or suppressed |
reason | Why the mail was not sent, or null |
Errors:
| Status | error | When |
|---|---|---|
| 422 | refused | Only invited users can be sent an invite; anna is active.; bob has no email address; create a new invite link instead. |
| 429 | rate_limited | Invitation email limit reached. Try again in an hour. (200 invitation emails per hour per admin) |
A new link for an invitation without email is created in the admin pages only.