---
title: Users API
path: reference/api/users
status: published
---

# 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](/docs/scaikey/concepts/tokens-and-scopes) and [Reference → OAuth endpoints](/docs/scaikey/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`](#schema-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`](#schema-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`](#schema-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`](#schema-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`](#schema-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`](#schema-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`](#schema-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`](#schema-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`](#schema-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`](#schema-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`](#schema-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_`](#schema-paginatedresponse-userlistitem) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-usercreate)

**Responses:**

| Status | Body |
|---|---|
| `201` | `application/json` → [`ApiResponse_UserResponse_`](#schema-apiresponse-userresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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` |  |

**Responses:**

| Status | Body |
|---|---|
| `204` | Successful Response |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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_`](#schema-apiresponse-userresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-userupdate)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_UserResponse_`](#schema-apiresponse-userresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-userpasswordreset)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-userstatusupdate)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-userresponse) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `HTTPValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `detail` | array of [`ValidationError`](#schema-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`](#schema-userlistitem) | yes |  |
| `pagination` | [`PaginationMeta`](#schema-paginationmeta) | yes |  |
| `meta` | [`MetaResponse`](#schema-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` (`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`](#schema-userstatus) | yes |  |
| `ou_path` | `string` \| `null` | no |  |
| `identity_source` | [`IdentitySource`](#schema-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`](#schema-userstatus) | yes |  |
| `identity_source` | [`IdentitySource`](#schema-identitysource) | yes |  |
| `mfa_enabled` | `boolean` | no | Default: `False` |
| `groups` | array of [`UserGroupMembership`](#schema-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`](#schema-userstatus) | yes |  |
| `reason` | `string` \| `null` | no |  |
| `terminate_sessions` | `boolean` | no | Default: `False` |

### `UserUpdate`

Schema for updating a user.

| Field | Type | Required | Description |
|---|---|---|---|
| `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 | Description |
|---|---|---|---|
| `loc` | array of `string` \| `integer` | yes |  |
| `msg` | `string` | yes |  |
| `type` | `string` | yes |  |