Users API

Reference for the Users endpoint group — 17 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)
`authorization`	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.

Parameters:

Name	In	Required	Type	Description
`authorization`	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`

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`

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`

Responses:

Status	Body
`200`	`application/json` → any
`422`	`application/json` → `HTTPValidationError`

PATCH `/api/v1/admin/users/{user_id}`#

Update User

Update a user.

Parameters:

Name	In	Required	Type	Description
`user_id`	path	yes	`string`
`authorization`	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`

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`

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`

Request body:

Required.

application/json → object

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`

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
`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`

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
`tenant_id`	path	yes	`string`
`user_id`	path	yes	`string`
`confirm_email`	query	yes	`string`

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
`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`

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`

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`

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
`data`	array of `UserListItem`	yes
`pagination`	`PaginationMeta`	yes
`meta`	`MetaResponse`	no

`PaginationMeta`#

Pagination metadata.

Field	Type	Required
`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` (`email`)	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` (`email`)	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`
`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
`email`	`string` (`email`) \| `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
`custom_attributes`	object \| `null`	no

`ValidationError`#

Field	Type	Required
`loc`	array of `string` \| `integer`	yes
`msg`	`string`	yes
`type`	`string`	yes

Users API

Authentication#

Endpoints#

GET /api/v1/admin/users/#

POST /api/v1/admin/users/#

GET /api/v1/admin/users/identity-source/mismatches#

DELETE /api/v1/admin/users/{user_id}#

GET /api/v1/admin/users/{user_id}#

PATCH /api/v1/admin/users/{user_id}#

GET /api/v1/admin/users/{user_id}/groups#

POST /api/v1/admin/users/{user_id}/mfa/disable#

POST /api/v1/admin/users/{user_id}/reset-password#

POST /api/v1/admin/users/{user_id}/unlock#

GET /api/v1/tenants/{tenant_id}/users#

POST /api/v1/tenants/{tenant_id}/users#

DELETE /api/v1/tenants/{tenant_id}/users/{user_id}#

GET /api/v1/tenants/{tenant_id}/users/{user_id}#

PATCH /api/v1/tenants/{tenant_id}/users/{user_id}#

POST /api/v1/tenants/{tenant_id}/users/{user_id}/password/reset#

PUT /api/v1/tenants/{tenant_id}/users/{user_id}/status#

Schemas#

ApiResponse_UserResponse_#

HTTPValidationError#

IdentitySource#

MetaResponse#

PaginatedResponse_UserListItem_#

PaginationMeta#

UserCreate#

UserGroupMembership#

UserListItem#

UserPasswordReset#

UserResponse#

UserStatus#

UserStatusUpdate#

UserUpdate#

ValidationError#

GET `/api/v1/admin/users/`#

POST `/api/v1/admin/users/`#

GET `/api/v1/admin/users/identity-source/mismatches`#

DELETE `/api/v1/admin/users/{user_id}`#

GET `/api/v1/admin/users/{user_id}`#

PATCH `/api/v1/admin/users/{user_id}`#

GET `/api/v1/admin/users/{user_id}/groups`#

POST `/api/v1/admin/users/{user_id}/mfa/disable`#

POST `/api/v1/admin/users/{user_id}/reset-password`#

POST `/api/v1/admin/users/{user_id}/unlock`#

GET `/api/v1/tenants/{tenant_id}/users`#

POST `/api/v1/tenants/{tenant_id}/users`#

DELETE `/api/v1/tenants/{tenant_id}/users/{user_id}`#

GET `/api/v1/tenants/{tenant_id}/users/{user_id}`#

PATCH `/api/v1/tenants/{tenant_id}/users/{user_id}`#

POST `/api/v1/tenants/{tenant_id}/users/{user_id}/password/reset`#

PUT `/api/v1/tenants/{tenant_id}/users/{user_id}/status`#

`ApiResponse_UserResponse_`#

`HTTPValidationError`#

`IdentitySource`#

`MetaResponse`#

`PaginatedResponse_UserListItem_`#

`PaginationMeta`#

`UserCreate`#

`UserGroupMembership`#

`UserListItem`#

`UserPasswordReset`#

`UserResponse`#

`UserStatus`#

`UserStatusUpdate`#

`UserUpdate`#

`ValidationError`#