# API Reference: Users

## GET `/users/login`

**Summary:** Initiate OIDC Login Flow

**Description:** Initiates the OIDC authentication flow.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `frontend_callback_uri` | query | No | anyOf | The frontend URI to redirect back to after OIDC provider. |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/users/login?frontend_callback_uri=<frontend_callback_uri>' \
  -H 'accept: application/json'
```

---

## GET `/users/login/callback`

**Summary:** Handle OIDC Login Callback

**Description:** Handles the callback from the OIDC provider.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `code` | query | Yes | string | Authorization code from OIDC provider |
| `state` | query | Yes | string | The original frontend redirect URI |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/users/login/callback?code=<code>&state=<state>' \
  -H 'accept: application/json'
```

---

## GET `/users/me`

**Summary:** Get Current User Status

**Description:** Checks the login status of the current user.
Requires a valid user_id to be present in the request header.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/users/me' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## POST `/users/login/local`

**Summary:** Local Authentication Fallback

**Description:** Day 1: Local Username/Password Login.

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `LocalLoginRequest` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/users/login/local' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## PUT `/users/password`

**Summary:** Update User Password

**Description:** Update User Password

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `PasswordUpdateRequest` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'PUT' \
  'http://localhost:8000/api/v1/users/password' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## GET `/users/me/profile`

**Summary:** Get Current User Profile

**Description:** Retrieves profile information for the current user.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/users/me/profile' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## PUT `/users/me/profile`

**Summary:** Update User Profile

**Description:** Updates profile details for the current user.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `UserProfileUpdate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'PUT' \
  'http://localhost:8000/api/v1/users/me/profile' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## GET `/users/me/config`

**Summary:** Get Current User Preferences

**Description:** Gets user specific preferences (LLM, TTS, STT config overrides).

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/users/me/config' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## PUT `/users/me/config`

**Summary:** Update Current User Preferences

**Description:** Updates user specific preferences.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `UserPreferences` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'PUT' \
  'http://localhost:8000/api/v1/users/me/config' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## GET `/users/me/config/models`

**Summary:** Get Models for Provider

**Description:** Get Models for Provider

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `provider_name` | query | Yes | string |  |
| `section` | query | No | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/users/me/config/models?provider_name=<provider_name>&section=<section>' \
  -H 'accept: application/json'
```

---

## GET `/users/me/config/providers`

**Summary:** Get All Valid Providers per Section

**Description:** Get All Valid Providers per Section

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `section` | query | No | string |  |
| `configured_only` | query | No | boolean | If true, only returns providers currently configured in preferences or system defaults |
| `x-user-id` | header | No | anyOf |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/users/me/config/providers?section=<section>&configured_only=<configured_only>' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## POST `/users/me/config/verify_llm`

**Summary:** Verify Llm

**Description:** Verify Llm

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `VerifyProviderRequest` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/users/me/config/verify_llm' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## POST `/users/me/config/verify_tts`

**Summary:** Verify Tts

**Description:** Verify Tts

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `VerifyProviderRequest` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/users/me/config/verify_tts' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## POST `/users/me/config/verify_stt`

**Summary:** Verify Stt

**Description:** Verify Stt

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `VerifyProviderRequest` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/users/me/config/verify_stt' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## POST `/users/logout`

**Summary:** Log Out the Current User

**Description:** Simulates a user logout. In a real application, this would clear the session token or cookie.

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/users/logout' \
  -H 'accept: application/json'
```

---

## GET `/users/me/config/export`

**Summary:** Export Configurations to YAML

**Description:** Exports the effective user configuration as a YAML file (Admin only).

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/users/me/config/export' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## POST `/users/me/config/import`

**Summary:** Import Configurations from YAML

**Description:** Imports user configuration from a YAML file.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `multipart/form-data`
- **Schema:** `Body_import_user_config_yaml_users_me_config_import_post` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/users/me/config/import' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/file'
```

---

## GET `/users/admin/users`

**Summary:** List All Users (Admin Only)

**Description:** Returns a list of all registered users in the system.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/users/admin/users' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## PUT `/users/admin/users/{uid}/role`

**Summary:** Update User Role (Admin Only)

**Description:** Updates a user's role. Prevents demoting the last administrator.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `uid` | path | Yes | string |  |
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `UserRoleUpdate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'PUT' \
  'http://localhost:8000/api/v1/users/admin/users/{uid}/role' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## PUT `/users/admin/users/{uid}/group`

**Summary:** Update User Group (Admin Only)

**Description:** Assigns a user to a group.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `uid` | path | Yes | string |  |
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `UserGroupUpdate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'PUT' \
  'http://localhost:8000/api/v1/users/admin/users/{uid}/group' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## GET `/users/admin/groups`

**Summary:** List All Groups (Admin Only)

**Description:** Returns all existing groups.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/users/admin/groups' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## POST `/users/admin/groups`

**Summary:** Create Group (Admin Only)

**Description:** Creates a new group.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `GroupCreate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/users/admin/groups' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## PUT `/users/admin/groups/{gid}`

**Summary:** Update Group (Admin Only)

**Description:** Updates a group's metadata or policy.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `gid` | path | Yes | string |  |
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `GroupUpdate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'PUT' \
  'http://localhost:8000/api/v1/users/admin/groups/{gid}' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## DELETE `/users/admin/groups/{gid}`

**Summary:** Delete Group (Admin Only)

**Description:** Deletes a group. Users are moved back to 'ungrouped'.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `gid` | path | Yes | string |  |
| `x-user-id` | header | No | anyOf |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'DELETE' \
  'http://localhost:8000/api/v1/users/admin/groups/{gid}' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

