API Keys

Updated Oct 4, 2026 Markdown

`GET /api/v1/system/api-keys`

List API keys

Returns every API key (without secrets — secrets are shown only at create time).

Responses:

Status	Schema	Description
`200`	`ApiSuccess_list_ApiKeyPublic__`	Successful Response

Response example (200):

JSON

{
  "data": [
    {
      "allowed_ips": "...",
      "created_at": "...",
      "id": "...",
      "key": "...",
      "last_used_at": "...",
      "name": "...",
      "owner": "...",
      "scopes": "...",
      "status": "..."
    }
  ],
  "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/system/api-keys

`POST /api/v1/system/api-keys`

Create API key

Mint a new HMAC API key pair. The secret is returned only once — subsequent reads only expose the key id + name + scopes.

Body fields:

Field	Type	Required	Notes
`allowed_ips`	array	no	—
`name`	string	yes	minLength=1; maxLength=100
`scopes`	array	no	—

Request body example:

JSON

{
  "allowed_ips": [
    "string"
  ],
  "name": "string",
  "scopes": [
    "string"
  ]
}

Responses:

Status	Schema	Description
`201`	`ApiSuccess_ApiKeyCreateResponse_`	Successful Response
`422`	`HTTPValidationError`	Validation Error

Response example (201):

JSON

{
  "data": {
    "allowed_ips": [
      "..."
    ],
    "created_at": "string",
    "id": "string",
    "key": "string",
    "name": "string",
    "owner": "...",
    "scopes": [
      "..."
    ],
    "secret": "string"
  },
  "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/system/api-keys

`GET /api/v1/system/api-keys/logs`

API access logs

Paginated history of every HMAC request — useful for debugging integration failures and reviewing key usage.

Query parameters:

Name	Type	Required	Notes
`page`	integer	no	minimum=1
`limit`	integer	no	minimum=1; maximum=100
`search`	string	no	—
`status`	string	no	—

Responses:

Status	Schema	Description
`200`	`ApiSuccess_PaginatedApiAccessLogsData_`	Successful Response
`422`	`HTTPValidationError`	Validation Error

Response example (200):

JSON

{
  "data": {
    "logs": [
      "..."
    ],
    "total": 0
  },
  "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/system/api-keys/logs

`DELETE /api/v1/system/api-keys/{key_id}`

Permanently delete API key

Hard-delete the key. Audit log entry is kept.

Path parameters:

Name	Type	Required	Notes
`key_id`	string	yes	—

Responses:

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

Response example (200):

JSON

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

cURL example:

shell

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/system/api-keys/{key_id}

`PUT /api/v1/system/api-keys/{key_id}`

Update API key metadata

Change name, allowed-IP whitelist or scope set. The secret cannot be rotated — revoke + re-create instead.

Path parameters:

Name	Type	Required	Notes
`key_id`	string	yes	—

Body fields:

Field	Type	Required	Notes
`allowed_ips`	array	no	—
`name`	string	no	—
`scopes`	array	no	—

Request body example:

JSON

{
  "allowed_ips": [
    "string"
  ],
  "name": "string",
  "scopes": [
    "string"
  ]
}

Responses:

Status	Schema	Description
`200`	`ApiSuccess_ApiKeyPublic_`	Successful Response
`422`	`HTTPValidationError`	Validation Error

Response example (200):

JSON

{
  "data": {
    "allowed_ips": [
      "..."
    ],
    "created_at": "string",
    "id": "string",
    "key": "string",
    "last_used_at": "...",
    "name": "string",
    "owner": "...",
    "scopes": [
      "..."
    ],
    "status": "active"
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell

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/system/api-keys/{key_id}

`POST /api/v1/system/api-keys/{key_id}/revoke`

Revoke API key (soft-disable)

Mark the key as revoked — subsequent HMAC requests with this key are rejected with 401.

Path parameters:

Name	Type	Required	Notes
`key_id`	string	yes	—

Responses:

Status	Schema	Description
`200`	`ApiSuccess_ApiKeyPublic_`	Successful Response
`422`	`HTTPValidationError`	Validation Error

Response example (200):

JSON

{
  "data": {
    "allowed_ips": [
      "..."
    ],
    "created_at": "string",
    "id": "string",
    "key": "string",
    "last_used_at": "...",
    "name": "string",
    "owner": "...",
    "scopes": [
      "..."
    ],
    "status": "active"
  },
  "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/system/api-keys/{key_id}/revoke

Still Need Help?

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