Sovrain
  1. Documentation
  2. Identity provider
  3. For developers
  4. Admin API

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"
}
FieldTypeNotes
idstringPublic id. The same value is the OpenID Connect sub and the externalId attribute.
loginstringLogin name. For people invited by email it is the address as it was typed.
emailstring or nullThe address as it was typed. Whether it is verified is not returned.
display_namestring or nullThe display name set on the profile
first_name, last_namestring or null
statusstringinvited (no password yet), suspended, or active
suspendedboolean
groupsarrayThe groups the user is in, each {id, name}. Always includes All.
attributesobjectCustom attribute values, key to string or null
created_atstring

Removed users are never returned.

List users

GET /api/v1/users

Scope: users:read

Query parameterNotes
qMatches part of the login, email, full name or “first last”, ignoring case
statusactive, invited or suspended. Any other value is ignored and returns everyone.
limit1 to 200. Default 50.
cursorThe 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:

FieldNotes
display_nameThe full name: the display name, else first and last name
ownerMember of the built-in group Owners
adminMember of the built-in group Admins. An owner who is not in Admins shows false.

Errors:

StatuserrorWhen
400invalid_requestlimit is not a number
422refusedlimit 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:

StatuserrorWhen
404not_foundUnknown user: external id 'x'

Change the profile

PATCH /api/v1/users/{id}

Scope: users:write

FieldTypeRequiredNotes
display_namestringnoLeft out: unchanged. Empty string: cleared.
first_namestringnoSame
last_namestringnoSame

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

FieldTypeRequiredNotes
attributesobjectyesThe 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:

StatuserrorWhen
422refusedSend '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

FieldTypeRequiredNotes
groupsarray of group idsyesThe 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:

StatuserrorWhen
422refusedSend '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:

StatuserrorWhen
422refusedYou 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:

StatuserrorWhen
404not_foundUnknown or already removed user
422refusedYou 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
}
FieldNotes
statussent, failed or suppressed
reasonWhy the mail was not sent, or null

Errors:

StatuserrorWhen
422refusedOnly invited users can be sent an invite; anna is active.; bob has no email address; create a new invite link instead.
429rate_limitedInvitation 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.