Authentication & Session

Updated Nov 19, 2026 Markdown

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:

shell
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

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": "[email protected]"
}

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:

shell
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

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:

shell
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

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:

shell
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

Open a one-time client sign-in link

The page login_url from POST /accounts/{username}/login-token opens (/api/v1/auth/client/login-link#token=<token>): it reads the token from the fragment, which the browser never sends, drops the fragment from the address bar and posts the token to POST /auth/client/login-token. Without a token it opens the client sign-in page.

Responses:

Status Schema Description
200 — Successful Response

cURL example:

shell
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/login-link

GET /api/v1/auth/client/login-token

Use a one-time client sign-in link (query form)

The earlier form of the link, ?token=<token> in the address: it still signs in as the posted form does (refusals are 302 to the client sign-in page). Deprecated — WHost no longer issues it, and the agent's access log writes its token as ***; open the login_url WHost returns instead.

Deprecated. Avoid in new integrations.

Query parameters:

Name Type Required Notes
token string no —

Responses:

Status Schema Description
200 — Successful Response
422 HTTPValidationError Validation Error

cURL example:

shell
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/login-token

POST /api/v1/auth/client/login-token

Use a one-time client sign-in link

Posted by the link's page (form field token): a live link signs into the account's client panel (session cookie, then the dashboard). The first use consumes the link; an unknown, used or expired link, another address than the one it is bound to, or an account that is no longer active is answered with 303 to the client sign-in page, without a session.

Responses:

Status Schema Description
200 — Successful Response

cURL example:

shell
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/login-token

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:

shell
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

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:

shell
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

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:

shell
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

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:

shell
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

GET /api/v1/auth/impersonate/callback

Open an impersonation link

The page login_url opens: it reads token (and lang) from the fragment, drops the fragment from the address bar and posts them to POST /auth/impersonate/callback/use. The query form (?token=<token>&lang=<lang>) still signs in as before; it is deprecated — WHost no longer issues it, and the agent's access log writes its token as ***.

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:

shell
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

POST /api/v1/auth/impersonate/callback/use

Use an impersonation link

Posted by the link's page (form fields token, lang). A valid token sets the client session and opens the client dashboard; any other answer is 303 to /<lang>/admin/.

Responses:

Status Schema Description
200 — Successful Response

cURL example:

shell
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/callback/use

POST /api/v1/auth/impersonate/{username}

Mint impersonation token

Generate a short-lived impersonation token (admin or reseller scope). Returns login_url, /api/v1/auth/impersonate/callback#token=<token>: the token rides after #, which the browser never sends, and the callback's page posts it. A lang appended to the URL (&lang=tr) lands in the same fragment and is posted with it.

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:

shell
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}

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:

shell
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

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:

shell
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

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:

shell
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

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:

shell
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

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:

shell
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
Still Need Help?

Our support team is here around the clock for anything you can't find above.