Create Client
POST /v1/clients
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 row. Unlike Get Client, this response does not include theroute_assignments array (route assignments only appear on GET /v1/clients/:id) and includes the raw tenant_id column.
import { KnoxCall } from "@knoxcall/sdk";
const client = new KnoxCall(); // credentials from `knoxcall login` or KNOXCALL_CLIENT_ID / KNOXCALL_CLIENT_SECRET
const created = await client.clients.create({
name: "Production Backend",
ip_address: "203.0.113.0/24",
type: "server",
description: "Main backend servers"
});
from knoxcall import KnoxCall
client = KnoxCall() # credentials from `knoxcall login` or KNOXCALL_CLIENT_ID / KNOXCALL_CLIENT_SECRET
created = client.clients.create(
name="Production Backend",
ip_address="203.0.113.0/24",
type="server",
description="Main backend servers"
)
# Mint a 1-hour OAuth token (client_credentials) — see /api-reference/authentication
TOKEN=$(curl -s -X POST https://api.knoxcall.com/oauth/token \
-u "$KNOXCALL_CLIENT_ID:$KNOXCALL_CLIENT_SECRET" \
-d "grant_type=client_credentials" | jq -r .access_token)
curl -X POST https://api.knoxcall.com/v1/clients \
-H "Authorization: Bearer $TOKEN" \
-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 |
| 409 | conflict | A client with this name already exists in this mode. Client names are unique per tenant per mode, so the same name may exist in both production and sandbox, but not twice within one |