Clients represent the machines or users authorized to call your proxy routes. Each client is identified by an IP address (or CIDR range) and can be assigned to specific routes to control access.
Clients are only enforced on routes where requires_clients is set to true. Routes without client restrictions accept requests from any source IP.
List Clients
Returns a paginated list of all clients in your tenant.
Query Parameters
| Parameter | Type | Default | Description |
|---|
page | integer | 1 | Page number |
per_page | integer | 20 | Items per page (max 100) |
sort | string | created_at | Sort by: created_at, name, type, or ip_address |
order | string | desc | Sort direction: asc or desc |
type | string | — | Filter by client type: user or server |
Response
{
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Production Backend",
"type": "server",
"ip_address": "203.0.113.0/24",
"ip_notes": {},
"description": "Main backend servers",
"enabled": true,
"collection_id": null,
"created_at": "2026-01-15T09:30:00.000Z",
"updated_at": "2026-02-20T11:00:00.000Z"
}
],
"meta": {
"total": 8,
"page": 1,
"per_page": 20,
"total_pages": 1,
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
curl "https://api.knoxcall.com/v1/clients?type=server" \
-H "Authorization: Bearer tk_live_abc123..."
Get Client
Returns a single client with its route assignments.
Path Parameters
| Parameter | Type | Description |
|---|
id | uuid | The client ID |
Response
{
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Production Backend",
"type": "server",
"ip_address": "203.0.113.0/24",
"ip_notes": {},
"description": "Main backend servers",
"enabled": true,
"collection_id": null,
"created_at": "2026-01-15T09:30:00.000Z",
"updated_at": "2026-02-20T11:00:00.000Z",
"route_assignments": [
{
"route_id": "rt-uuid-1",
"route_name": "Payment Gateway",
"environment_name": "production"
},
{
"route_id": "rt-uuid-2",
"route_name": "User Service",
"environment_name": "production"
}
]
},
"meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
Errors
| Status | Type | Description |
|---|
| 404 | not_found | Client not found |
Create Client
Creates a new authorized client.
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | Display name for the client |
ip_address | string | Yes | IP address or CIDR range (e.g., 203.0.113.42 or 10.0.0.0/16) |
type | string | No | Client type: user or server (defaults to server) |
ip_notes | object | No | Metadata about the IP address |
description | string | No | Human-readable description |
Response
Returns the created client object (same shape as Get Client).
curl -X POST https://api.knoxcall.com/v1/clients \
-H "Authorization: Bearer tk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{
"name": "Production Backend",
"ip_address": "203.0.113.0/24",
"type": "server",
"description": "Main backend servers"
}'
Errors
| Status | Type | Description |
|---|
| 400 | validation_error | Missing required fields or invalid type |
| 403 | plan_limit | Client limit reached for your subscription plan |
Update Client
Updates one or more fields on an existing client.
Path Parameters
| Parameter | Type | Description |
|---|
id | uuid | The client ID |
Request Body
All fields are optional. Only provided fields will be updated.
| Field | Type | Description |
|---|
name | string | Display name |
type | string | Client type: user or server |
ip_address | string | IP address or CIDR range |
ip_notes | object | IP metadata |
description | string | Description |
enabled | boolean | Enable or disable the client |
Response
Returns the updated client object.
Errors
| Status | Type | Description |
|---|
| 400 | validation_error | No valid fields provided or invalid type |
| 404 | not_found | Client not found |
Delete Client
Permanently deletes a client and removes it from all route assignments.
Path Parameters
| Parameter | Type | Description |
|---|
id | uuid | The client ID |
Response
{
"data": { "deleted": true },
"meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
Errors
| Status | Type | Description |
|---|
| 404 | not_found | Client not found |
