Admin Profile
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):
{
"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:
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
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:
{
"email": "string",
"language": "string",
"sidebar_collapsed": false
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_AdminProfileResponse_ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"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:
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
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):
{
"data": {
"codes": [
"..."
]
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
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
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:
{
"password": "REPLACE_ME"
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
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
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:
{
"code": "string"
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_BackupCodesResponse_ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {
"codes": [
"..."
]
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
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
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):
{
"data": {},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
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
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:
{
"method": "totp"
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_TwoFASetupResponse_ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {
"masked_email": "...",
"method": "totp",
"otpauth_uri": "...",
"secret": "..."
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
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
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):
{
"data": {},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
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
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:
{
"avatar": "string"
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_dict_str__Any__ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
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
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:
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
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:
{
"current_password": "REPLACE_ME",
"new_password": "REPLACE_ME"
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
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
GET /api/v1/admin/profile/setup-guide
Get the setup guide
The admin's setup guide in one read: whether it opens by itself and whether its dashboard card shows, the facts its three settings start from (caller's address, admin allowlist, two-factor and sign-in CAPTCHA state, alert e-mail, nightly schedule for new accounts) and the live facts behind its list (panel certificate, name servers, plan and account counts, the last package check). Session-only. Starts no package scan.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_SetupGuideStatus_ |
Successful Response |
Response example (200):
{
"data": {
"accounts": 0,
"admin_allowed_ips": [
"..."
],
"backups": "...",
"certificate": "...",
"client_ip": "string",
"client_ip_listed": false,
"hidden_at": "...",
"hostname": "string",
"login_captcha_enabled": false,
"nameservers": [
"..."
],
"notify_email": "[email protected]",
"open_on_sign_in": false,
"os_updates": "...",
"plans": 0,
"seen_at": "...",
"two_factor_enabled": false,
"visible": false
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
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/setup-guide
PUT /api/v1/admin/profile/setup-guide
Update the setup guide marks
seen: true records that the first-sign-in guide was shown (it no longer opens by itself), seen: false lets it open again; hidden hides or shows the dashboard card. Kept in the agent's admin state file, not in agent.conf. Session-only.
Body fields:
| Field | Type | Required | Notes |
|---|---|---|---|
hidden |
boolean | no | true: hide the dashboard card · false: show it again. |
seen |
boolean | no | true: the first-sign-in guide was shown · false: show it again on the next visit. |
Request body example:
{
"hidden": false,
"seen": false
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_SetupGuideStatus_ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {
"accounts": 0,
"admin_allowed_ips": [
"..."
],
"backups": "...",
"certificate": "...",
"client_ip": "string",
"client_ip_listed": false,
"hidden_at": "...",
"hostname": "string",
"login_captcha_enabled": false,
"nameservers": [
"..."
],
"notify_email": "[email protected]",
"open_on_sign_in": false,
"os_updates": "...",
"plans": 0,
"seen_at": "...",
"two_factor_enabled": false,
"visible": false
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
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/setup-guide
Our support team is here around the clock for anything you can't find above.