# Admin Profile

<a id="get-api-v1-admin-profile"></a>
#### `GET /api/v1/admin/profile`

*Get admin profile*

Returns the current admin's profile (username, email, language, avatar URL, 2FA state).

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_AdminProfileResponse_` | Successful Response |

**Response example (200):**

```json
{
  "data": {
    "avatar_url": "...",
    "email": "",
    "language": "auto",
    "last_login": "...",
    "sidebar_collapsed": "...",
    "two_factor_enabled": false,
    "two_factor_method": "",
    "username": "alice"
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/admin/profile
```

---

<a id="put-api-v1-admin-profile"></a>
#### `PUT /api/v1/admin/profile`

*Update admin profile*

Patch email, language and/or the sidebar choice. Session-only — HMAC keys cannot mutate admin credentials. The sidebar choice is kept in the agent's admin state file, not in agent.conf.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `email` | string | no | — |
| `language` | string | no | — |
| `sidebar_collapsed` | boolean | no | The sidebar choice to keep: true collapsed, false expanded. |

**Request body example:**

```json
{
  "email": "string",
  "language": "string",
  "sidebar_collapsed": false
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_AdminProfileResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "avatar_url": "...",
    "email": "",
    "language": "auto",
    "last_login": "...",
    "sidebar_collapsed": "...",
    "two_factor_enabled": false,
    "two_factor_method": "",
    "username": "alice"
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X PUT \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/admin/profile
```

---

<a id="post-api-v1-admin-profile-2fa-backup-codes-regenerate"></a>
#### `POST /api/v1/admin/profile/2fa/backup-codes/regenerate`

*Regenerate backup codes*

Issues a fresh batch of one-time backup codes. Old codes are invalidated.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_BackupCodesResponse_` | Successful Response |

**Response example (200):**

```json
{
  "data": {
    "codes": [
      "..."
    ]
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/admin/profile/2fa/backup-codes/regenerate
```

---

<a id="post-api-v1-admin-profile-2fa-disable"></a>
#### `POST /api/v1/admin/profile/2fa/disable`

*Disable 2FA*

Requires the current admin password. Clears stored TOTP secret + backup codes.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `password` | string | yes | minLength=1 |

**Request body example:**

```json
{
  "password": "REPLACE_ME"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/admin/profile/2fa/disable
```

---

<a id="post-api-v1-admin-profile-2fa-enable"></a>
#### `POST /api/v1/admin/profile/2fa/enable`

*Verify OTP and enable 2FA*

Verifies the OTP from `/2fa/setup` and activates 2FA. **Returns the one-time backup codes** — they cannot be retrieved later. Anti-replay: rejects re-use of the same TOTP step.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `code` | string | yes | minLength=6; maxLength=6; pattern=`^\d{6}$` |

**Request body example:**

```json
{
  "code": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_BackupCodesResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "codes": [
      "..."
    ]
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/admin/profile/2fa/enable
```

---

<a id="post-api-v1-admin-profile-2fa-resend-code"></a>
#### `POST /api/v1/admin/profile/2fa/resend-code`

*Resend email 2FA code*

Only valid mid-setup when `method=email`. Response data: `{masked_email}`.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/admin/profile/2fa/resend-code
```

---

<a id="post-api-v1-admin-profile-2fa-setup"></a>
#### `POST /api/v1/admin/profile/2fa/setup`

*Initiate 2FA setup*

Begin two-factor enrollment. `method=totp` returns the secret + `otpauth://` URI for QR rendering. `method=email` sends an OTP to the configured admin email and returns the masked address.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `method` | string | no | default `totp`; pattern=`^(totp\|email)$` |

**Request body example:**

```json
{
  "method": "totp"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_TwoFASetupResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "masked_email": "...",
    "method": "totp",
    "otpauth_uri": "...",
    "secret": "..."
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/admin/profile/2fa/setup
```

---

<a id="delete-api-v1-admin-profile-avatar"></a>
#### `DELETE /api/v1/admin/profile/avatar`

*Delete admin avatar*

Removes the avatar file from disk and clears the persisted URL. Response data: `{avatar_url: null}`.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/admin/profile/avatar
```

---

<a id="post-api-v1-admin-profile-avatar"></a>
#### `POST /api/v1/admin/profile/avatar`

*Upload admin avatar*

Accepts PNG / JPEG / WebP up to 2 MB (magic-byte validated). Response data: `{avatar_url}` — short cache-busted URL to `/avatar/raw`.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `avatar` | string | yes | — |

**Request body example:**

```json
{
  "avatar": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/admin/profile/avatar
```

---

<a id="get-api-v1-admin-profile-avatar-raw"></a>
#### `GET /api/v1/admin/profile/avatar/raw`

*Stream admin avatar binary*

Returns the image bytes with the original Content-Type. Honors `If-None-Match` for 304 caching. Binary — no JSON envelope.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | — | Successful Response |

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/admin/profile/avatar/raw
```

---

<a id="patch-api-v1-admin-profile-password"></a>
#### `PATCH /api/v1/admin/profile/password`

*Change admin password*

Requires current password. On success the session secret is rotated (invalidating every other session) and a fresh session cookie is issued for the caller.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `current_password` | string | yes | minLength=1 |
| `new_password` | string | yes | At least 8 characters and at most 72 bytes when UTF-8 encoded.; minLength=8; maxLength=128 |

**Request body example:**

```json
{
  "current_password": "REPLACE_ME",
  "new_password": "REPLACE_ME"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X PATCH \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/admin/profile/password
```

---