Users API
Reference for the Users endpoint group — 20 endpoints.
Generated from the live OpenAPI spec. Re-run _generate_api_reference.py after backend changes.
Authentication#
All endpoints require a Bearer JWT in the Authorization header unless noted otherwise. See Concepts → Tokens and scopes and Reference → OAuth endpoints for how to obtain one.
Endpoints#
GET /api/v1/admin/users/#
List Users
List users with filtering.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
page |
query | no | integer |
|
per_page |
query | no | integer |
|
search |
query | no | string | null |
|
status |
query | no | string | null |
|
tenant_id |
query | no | string | null |
|
partner_id |
query | no | string | null |
Filter by partner (all tenants in partner) |
include_deleted |
query | no | boolean |
Include soft-deleted users (admins only) |
deleted_only |
query | no | boolean |
Return only soft-deleted users (admins only) |
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/admin/users/#
Create User
Create a new user.
Request body (application/json):
| Field | Type | Required | Notes |
|---|---|---|---|
email |
string | yes | Unique within the tenant. |
tenant_id |
string | yes | The user's tenant. For a non-super admin it must be a tenant in scope; an out-of-scope value is pinned to the admin's own. |
password |
string | no | Omit to create a user with no usable password (they set one via password reset). |
first_name |
string | no | |
last_name |
string | no | |
display_name |
string | no | Defaults from first/last name, else the email local-part. |
status |
string | no | Default ACTIVE. |
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Request body:
Required.
application/json→ object
Responses:
| Status | Body |
|---|---|
201 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/admin/users/identity-source/mismatches#
Get Identity Source Mismatches
Find users with identity_source mismatches.
A mismatch occurs when:
- User has a federated identity to an LDAP IdP but identity_source != 'LDAP'
- User has a federated identity to an OIDC IdP but identity_source != 'OIDC'
- etc.
Use fix=true to automatically correct these mismatches.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
query | no | string | null |
|
fix |
query | no | boolean |
If true, automatically fix the mismatches |
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
DELETE /api/v1/admin/users/{user_id}#
Delete User
Soft delete a user.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
204 |
Successful Response |
422 |
application/json → HTTPValidationError |
GET /api/v1/admin/users/{user_id}#
Get User
Get a user by ID.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
PATCH /api/v1/admin/users/{user_id}#
Update User
Update a user.
Notable body field: manager_id — the user's manager, as another user's id
(usr_…) in the same tenant. Optional and nullable; send ""/null to
clear. Validated (must be a live user in the same tenant, not the user
themselves). For AD-backed tenants this is set automatically by LDAP sync
(resolved from the AD manager DN); for local tenants set it here.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Request body:
Required.
application/json→ object
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/admin/users/{user_id}/devices#
Admin List User Devices
List a user's E2E-encryption devices (admin view).
The admin equivalent of GET /me/devices — same shape as the
directory queries and same set of fields (id, kind, platform,
public keys, key_version, timestamps, online, revocation
state) so the Users detail page can render devices with the same
component the directory search uses.
Access: super_admin sees any user; partner/tenant admins see users in tenants they can reach.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
|
include_revoked |
query | no | boolean |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/admin/users/{user_id}/devices/{device_id}/revoke#
Admin Revoke Device
Revoke a user's device (admin action).
Body: {"reason": "<enum value>"}. Canonical values:
admin_revoked (default) | key_compromise_suspected |
rotation_replacement | user_revoked. Free-form strings
still accepted but downstream consumers may treat non-canonical
values as generic. The reason is persisted on the device row and
echoed in the webhook payload; downstream consumers use it to
distinguish an operator's kill-switch from a user's routine "I
lost my laptop" self-revoke.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
|
device_id |
path | yes | string |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Request body:
Required.
application/json→ object
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/admin/users/{user_id}/groups#
Get User Groups
Get all groups a user belongs to.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/admin/users/{user_id}/mfa/disable#
Disable User Mfa
Disable MFA for a user (admin action).
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/admin/users/{user_id}/reset-password#
Reset User Password
Reset a user's password (admin sets new password directly).
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Request body:
Required.
application/json→ object
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/admin/users/{user_id}/restore#
Restore User
Restore a soft-deleted user.
The companion to DELETE: clears deleted_at and resets the row to ACTIVE. Necessary because the unique (tenant_id, email) constraint includes soft-deleted rows, so a brand-new create with the same email would fail.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/admin/users/{user_id}/unlock#
Unlock User
Unlock a locked user account and reset failed login attempts.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/tenants/{tenant_id}/users#
List Users
List users in the tenant directory.
Requires admin authentication. Apps should use the effective-users endpoint instead.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
page |
query | no | integer |
|
per_page |
query | no | integer |
|
search |
query | no | string | null |
|
status |
query | no | UserStatus | null |
|
ou_id |
query | no | string | null |
|
group_id |
query | no | string | null |
|
mfa_enabled |
query | no | boolean | null |
|
sort_by |
query | no | string |
|
sort_order |
query | no | string |
|
authorization |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → PaginatedResponse_UserListItem_ |
422 |
application/json → HTTPValidationError |
POST /api/v1/tenants/{tenant_id}/users#
Create User
Create a new user in the tenant directory.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
authorization |
header | no | string | null |
Request body:
Required.
application/json→UserCreate
Responses:
| Status | Body |
|---|---|
201 |
application/json → ApiResponse_UserResponse_ |
422 |
application/json → HTTPValidationError |
DELETE /api/v1/tenants/{tenant_id}/users/{user_id}#
Delete User
Delete a user (soft delete).
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
user_id |
path | yes | string |
|
confirm_email |
query | yes | string |
|
authorization |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
204 |
Successful Response |
422 |
application/json → HTTPValidationError |
GET /api/v1/tenants/{tenant_id}/users/{user_id}#
Get User
Get a user by ID.
Authentication:
- Admin users can access any user in their scope
- Applications can access users assigned to them (directly or via group)
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
user_id |
path | yes | string |
|
include |
query | no | string | null |
|
authorization |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → ApiResponse_UserResponse_ |
422 |
application/json → HTTPValidationError |
PATCH /api/v1/tenants/{tenant_id}/users/{user_id}#
Update User
Update a user's attributes.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
user_id |
path | yes | string |
|
authorization |
header | no | string | null |
Request body:
Required.
application/json→UserUpdate
Responses:
| Status | Body |
|---|---|
200 |
application/json → ApiResponse_UserResponse_ |
422 |
application/json → HTTPValidationError |
POST /api/v1/tenants/{tenant_id}/users/{user_id}/password/reset#
Reset User Password
Reset a user's password (admin action).
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
user_id |
path | yes | string |
|
authorization |
header | no | string | null |
Request body:
Required.
application/json→UserPasswordReset
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
PUT /api/v1/tenants/{tenant_id}/users/{user_id}/status#
Update User Status
Update a user's status (enable, disable, lock, unlock).
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
user_id |
path | yes | string |
|
authorization |
header | no | string | null |
Request body:
Required.
application/json→UserStatusUpdate
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
Schemas#
Definitions for every type referenced by the endpoints above. Schema-to-schema references on this page link within the page; cross-page references would require visiting the linked page.
ApiResponse_UserResponse_#
| Field | Type | Required | Description |
|---|---|---|---|
data |
UserResponse |
yes | |
meta |
MetaResponse |
no |
HTTPValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
detail |
array of ValidationError |
no |
IdentitySource#
How the user was provisioned / identity source.
Type: string (enum)
Values: LOCAL, OIDC, SAML, SCIM, LDAP
MetaResponse#
Metadata included in API responses.
| Field | Type | Required | Description |
|---|---|---|---|
request_id |
string | null |
no | |
timestamp |
string (date-time) |
no |
PaginatedResponse_UserListItem_#
| Field | Type | Required | Description |
|---|---|---|---|
data |
array of UserListItem |
yes | |
pagination |
PaginationMeta |
yes | |
meta |
MetaResponse |
no |
PaginationMeta#
Pagination metadata.
| Field | Type | Required | Description |
|---|---|---|---|
page |
integer |
yes | |
per_page |
integer |
yes | |
total_items |
integer |
yes | |
total_pages |
integer |
yes |
UserCreate#
Schema for creating a new user.
| Field | Type | Required | Description |
|---|---|---|---|
email |
string |
yes | |
username |
string | null |
no | |
first_name |
string | null |
no | |
last_name |
string | null |
no | |
display_name |
string | null |
no | |
phone |
string | null |
no | |
locale |
string |
no | Default: en |
timezone |
string |
no | Default: UTC |
password |
string | null |
no | |
ou_id |
string | null |
no | |
group_ids |
array of string |
no | |
custom_attributes |
object | null |
no | |
require_password_change |
boolean |
no | Default: False |
send_welcome_email |
boolean |
no | Default: True |
UserGroupMembership#
Group membership info for a user.
| Field | Type | Required | Description |
|---|---|---|---|
group_id |
string |
yes | |
name |
string |
yes | |
membership_type |
string |
no | Default: DIRECT |
UserListItem#
Abbreviated user info for lists.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string |
yes | |
email |
string |
yes | |
display_name |
string | null |
no | |
status |
UserStatus |
yes | |
ou_path |
string | null |
no | |
identity_source |
IdentitySource |
yes | |
mfa_enabled |
boolean |
no | Default: False |
last_login_at |
string (date-time) | null |
no |
UserPasswordReset#
Schema for password reset request.
| Field | Type | Required | Description |
|---|---|---|---|
method |
string |
no | Default: EMAIL |
new_password |
string | null |
no | |
redirect_uri |
string | null |
no |
UserResponse#
Full user response.
| Field | Type | Required | Description |
|---|---|---|---|
email |
string |
yes | |
username |
string | null |
no | |
first_name |
string | null |
no | |
last_name |
string | null |
no | |
display_name |
string | null |
no | |
phone |
string | null |
no | |
locale |
string |
no | Default: en |
timezone |
string |
no | Default: UTC |
id |
string |
yes | |
email_verified |
boolean |
no | Default: False |
manager_id |
string | null |
no | |
manager_display_name |
string | null |
no | |
avatar_url |
string | null |
no | |
ou_id |
string | null |
no | |
ou_path |
string | null |
no | |
status |
UserStatus |
yes | |
identity_source |
IdentitySource |
yes | |
mfa_enabled |
boolean |
no | Default: False |
groups |
array of UserGroupMembership |
no | |
custom_attributes |
object | null |
no | |
created_at |
string (date-time) |
yes | |
updated_at |
string (date-time) | null |
no | |
last_login_at |
string (date-time) | null |
no | |
password_changed_at |
string (date-time) | null |
no |
UserStatus#
User account status.
Type: string (enum)
Values: ACTIVE, PENDING_EMAIL_VERIFICATION, PENDING_APPROVAL, DISABLED, LOCKED
UserStatusUpdate#
Schema for updating user status.
| Field | Type | Required | Description |
|---|---|---|---|
status |
UserStatus |
yes | |
reason |
string | null |
no | |
terminate_sessions |
boolean |
no | Default: False |
UserUpdate#
Schema for updating a user.
| Field | Type | Required | Description |
|---|---|---|---|
email |
string | null |
no | |
username |
string | null |
no | |
first_name |
string | null |
no | |
last_name |
string | null |
no | |
display_name |
string | null |
no | |
phone |
string | null |
no | |
locale |
string | null |
no | |
timezone |
string | null |
no | |
ou_id |
string | null |
no | |
manager_id |
string | null |
no | |
custom_attributes |
object | null |
no |
ValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
loc |
array of string | integer |
yes | |
msg |
string |
yes | |
type |
string |
yes |