API keys authenticate requests to the KnoxCall Management API. You can create multiple keys per tenant for different services and revoke them independently.
The type of key created depends on which environment you’re using. Keys created via api.knoxcall.com are production keys (tk_live_). Keys created via sandbox.knoxcall.com are test keys (tk_test_). See the Authentication guide for details.
List API Keys
Returns a paginated list of API keys for your tenant. Key values are masked — only the prefix is shown.
Query Parameters
| Parameter | Type | Default | Description |
|---|
page | integer | 1 | Page number |
per_page | integer | 20 | Items per page (max 100) |
Response
{
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"key_id": "tk_live_abc123",
"key_prefix": "tk_live_abc...",
"key_type": "standard",
"name": "Backend Server",
"active": true,
"created_at": "2026-01-15T09:30:00.000Z",
"last_used_at": "2026-03-10T14:22:01.000Z",
"rate_limit_requests": null,
"rate_limit_window_sec": null
}
],
"meta": {
"total": 3,
"page": 1,
"per_page": 20,
"total_pages": 1,
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
curl https://api.knoxcall.com/v1/api-keys \
-H "Authorization: Bearer tk_live_abc123..."
Create API Key
Creates a new API key. The full key value is returned only once in the response — store it securely.
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | A descriptive name (e.g., “CI/CD Pipeline”, “Backend Server”) |
rate_limit_requests | integer | No | Maximum requests per window for this key |
rate_limit_window_sec | integer | No | Rate limit window duration in seconds |
Response
{
"data": {
"key_id": "tk_live_newkey789",
"api_key": "tk_live_newkey789_a1b2c3d4e5f6g7h8i9j0...",
"key_prefix": "tk_live_new...",
"key_type": "standard",
"name": "CI/CD Pipeline",
"message": "Store this API key securely. It will not be shown again."
},
"meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
The api_key field contains the full key and is only returned at creation time. KnoxCall does not store the plain-text key. If you lose it, you must revoke it and create a new one.
curl -X POST https://api.knoxcall.com/v1/api-keys \
-H "Authorization: Bearer tk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{
"name": "CI/CD Pipeline"
}'
Errors
| Status | Type | Description |
|---|
| 400 | validation_error | Missing name field |
Revoke API Key
Revokes an API key, permanently disabling it. Revoked keys cannot be reactivated.
Path Parameters
| Parameter | Type | Description |
|---|
id | string | The API key ID (UUID or key_id) |
Response
{
"data": { "revoked": true },
"meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
You cannot revoke the API key that you are currently using to authenticate the request. Use a different key to revoke it, or revoke it from the dashboard.
Errors
| Status | Type | Description |
|---|
| 400 | validation_error | Cannot revoke the key currently in use |
| 404 | not_found | API key not found |
