# Authentication & Session

<a id="get-api-v1-auth-captcha-config"></a>
#### `GET /api/v1/auth/captcha-config`

*Captcha config (public)*

Return public captcha configuration for login pages. No authentication required.

**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 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/auth/captcha-config
```

---

<a id="post-api-v1-auth-client-forgot-password"></a>
#### `POST /api/v1/auth/client/forgot-password`

*Client forgot password*

Send a password reset link to the client's email. Always returns 200 to prevent email enumeration.

**Body fields:**

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

**Request body example:**

```json
{
  "email": "user@example.com"
}
```

**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/auth/client/forgot-password
```

---

<a id="get-api-v1-auth-client-impersonation-info"></a>
#### `GET /api/v1/auth/client/impersonation-info`

*Client impersonation info*

Return impersonation metadata for the current client session (impersonated flag + impersonator + role). Requires a client session.

**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 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/auth/client/impersonation-info
```

---

<a id="post-api-v1-auth-client-login"></a>
#### `POST /api/v1/auth/client/login`

*Client login*

Authenticate client account credentials. Returns either a session cookie (success) or a pending 2FA token when 2FA is enabled. A signed-in answer carries the account's panel choices: `data.language` (`auto` when none) and `data.sidebar_collapsed` (null when none).

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `identifier` | string | yes | — |
| `password` | string | yes | — |
| `recaptcha_token` | string | no | — |
| `remember_me` | boolean | no | default `False` |

**Request body example:**

```json
{
  "identifier": "string",
  "password": "REPLACE_ME",
  "recaptcha_token": "string",
  "remember_me": false
}
```

**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/auth/client/login
```

---

<a id="post-api-v1-auth-client-login-2fa"></a>
#### `POST /api/v1/auth/client/login/2fa`

*Client 2FA verify*

Verify the second-factor code during client login and issue a session cookie. `data.language` and `data.sidebar_collapsed` are set on the same terms as on the first step.

**Body fields:**

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

**Request body example:**

```json
{
  "code": "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/auth/client/login/2fa
```

---

<a id="post-api-v1-auth-client-logout"></a>
#### `POST /api/v1/auth/client/logout`

*Client logout*

Invalidate the client session cookie and bump the per-account session ratchet.

**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/auth/client/logout
```

---

<a id="post-api-v1-auth-client-reset-password"></a>
#### `POST /api/v1/auth/client/reset-password`

*Client reset password*

Reset a client account password using a valid one-time reset token.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `new_password` | string | yes | — |
| `token` | string | yes | — |

**Request body example:**

```json
{
  "new_password": "REPLACE_ME",
  "token": "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/auth/client/reset-password
```

---

<a id="get-api-v1-auth-client-session"></a>
#### `GET /api/v1/auth/client/session`

*Client session check*

Return the current client session status (authenticated/role/username/domain + optional 2FA setup hint).

**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 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/auth/client/session
```

---

<a id="get-api-v1-auth-impersonate-callback"></a>
#### `GET /api/v1/auth/impersonate/callback`

*Impersonate Callback*

Validate impersonation token, set client cookie, redirect to client panel.

**Query parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `token` | string | no | — |
| `lang` | string | no | — |

**Responses:**

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

**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/auth/impersonate/callback
```

---

<a id="post-api-v1-auth-impersonate-username"></a>
#### `POST /api/v1/auth/impersonate/{username}`

*Mint impersonation token*

Generate a short-lived impersonation token (admin or reseller scope). Returns a login URL for the callback endpoint.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |

**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)" \
  https://your-server:2000/api/v1/auth/impersonate/{username}
```

---

<a id="get-api-v1-auth-ip-check"></a>
#### `GET /api/v1/auth/ip-check`

*Admin IP allowlist check (public)*

Tells the login page whether the caller's address passes the admin IP allowlist. The resolved address is never echoed back.

**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 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/auth/ip-check
```

---

<a id="post-api-v1-auth-login"></a>
#### `POST /api/v1/auth/login`

*Admin login*

Authenticate admin credentials. Returns either a session cookie (success) or a pending 2FA token when 2FA is enabled. While the licence is not activated or is suspended, matching credentials still get the session and `data.license_blocked` names the condition (`LICENSE_NOT_ACTIVATED` or `LICENSE_SUSPENDED`); that session is honoured on the `/auth/*` and `/license/*` endpoints only, every other endpoint keeps answering 403 with the same code. A request that does not authenticate is answered 401 whatever the licence state. A signed-in answer carries the admin's panel choices: `data.language` (`auto` when none) and `data.sidebar_collapsed` (null when none).

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `identifier` | string | yes | — |
| `password` | string | yes | — |
| `recaptcha_token` | string | no | — |
| `remember_me` | boolean | no | default `False` |

**Request body example:**

```json
{
  "identifier": "string",
  "password": "REPLACE_ME",
  "recaptcha_token": "string",
  "remember_me": false
}
```

**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/auth/login
```

---

<a id="post-api-v1-auth-login-2fa"></a>
#### `POST /api/v1/auth/login/2fa`

*Admin 2FA verify*

Verify the second-factor code during admin login and issue a session cookie. `data.license_blocked`, `data.language` and `data.sidebar_collapsed` are set on the same terms as on the first step.

**Body fields:**

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

**Request body example:**

```json
{
  "code": "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/auth/login/2fa
```

---

<a id="post-api-v1-auth-logout"></a>
#### `POST /api/v1/auth/logout`

*Admin logout*

Invalidate the admin session cookie and bump the server-side session ratchet.

**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/auth/logout
```

---

<a id="get-api-v1-auth-session"></a>
#### `GET /api/v1/auth/session`

*Admin session check*

Return the current admin session status (authenticated/role/username + optional 2FA setup hint).

**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 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/auth/session
```

---