Documentation Index
Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
Use this file to discover all available pages before exploring further.
Each client can have one or more credentials — the actual authentication materials KnoxCall checks when a request arrives. Two credential kinds are available in v1:
| Kind | Description |
|---|
ip | An IP address or CIDR range. Matched against the incoming source IP. |
mtls_thumbprint | A client certificate SHA-256 thumbprint for mTLS authentication. KnoxCall can issue the certificate for you (mode: "issue") or you can register an existing cert’s thumbprint. |
List Credentials
GET /v1/clients/:id/credentials
Path Parameters
| Parameter | Type | Description |
|---|
id | uuid | The client ID |
Response
{
"data": [
{
"id": "cred-uuid-1",
"client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"kind": "ip",
"label": "Primary office",
"data": { "value": "203.0.113.0/24" },
"enabled": true,
"expires_at": null,
"created_at": "2026-01-15T09:30:00.000Z",
"updated_at": "2026-01-15T09:30:00.000Z",
"last_matched_at": "2026-05-20T14:22:01.000Z"
}
],
"meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
Errors
| Status | Type | Description |
|---|
| 404 | not_found | Client not found |
Add Credential
POST /v1/clients/:id/credentials
Path Parameters
| Parameter | Type | Description |
|---|
id | uuid | The client ID |
Request Body
| Field | Type | Required | Description |
|---|
kind | string | Yes | Credential type: ip or mtls_thumbprint |
label | string | No | Human-readable label |
data | object | Yes | Kind-specific data (see below) |
kind: "ip":
{ "value": "203.0.113.42" }
value must be a valid IPv4/IPv6 address or CIDR range.
For kind: "mtls_thumbprint" — issue a new certificate:
KnoxCall mints a certificate from your tenant CA, stores only the thumbprint, and returns the PEM bundle once in the reveal field. The private key is never stored.
For kind: "mtls_thumbprint" — register an existing certificate:
{ "sha256_thumbprint": "a1b2c3...64-hex-chars" }
Response
{
"data": {
"id": "cred-uuid-1",
"client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"kind": "ip",
"label": "Primary office",
"data": { "value": "203.0.113.0/24" },
"enabled": true,
"expires_at": null,
"created_at": "2026-01-15T09:30:00.000Z",
"updated_at": "2026-01-15T09:30:00.000Z",
"last_matched_at": null
},
"meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
mtls_thumbprint with mode: "issue", the response also includes a one-time reveal field:
{
"data": {
"id": "cred-uuid-2",
"kind": "mtls_thumbprint",
"data": { "sha256_thumbprint": "a1b2...", "subject": "CN=...", "serial": "...", "not_after": "2027-01-15T09:30:00Z" },
"enabled": true,
"expires_at": "2027-01-15T09:30:00Z",
"reveal": {
"certificate_pem": "-----BEGIN CERTIFICATE-----\n...",
"private_key_pem": "-----BEGIN PRIVATE KEY-----\n...",
"ca_chain_pem": "-----BEGIN CERTIFICATE-----\n..."
}
},
"meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
The reveal.private_key_pem is returned only once. Store it immediately — it is not retrievable again.
Errors
| Status | Type | Description |
|---|
| 400 | validation_error | Missing or invalid kind, or invalid data for the kind |
| 404 | not_found | Client not found |
Update Credential
PATCH /v1/clients/:id/credentials/:credId
Path Parameters
| Parameter | Type | Description |
|---|
id | uuid | The client ID |
credId | uuid | The credential ID |
Request Body
At least one field is required.
| Field | Type | Description |
|---|
enabled | boolean | Enable or disable this credential |
label | string | Update the credential label |
Response
Returns the updated credential object.
Errors
| Status | Type | Description |
|---|
| 400 | validation_error | Neither enabled nor label provided |
| 404 | not_found | Credential not found |
Delete Credential
DELETE /v1/clients/:id/credentials/:credId
Path Parameters
| Parameter | Type | Description |
|---|
id | uuid | The client ID |
credId | uuid | The credential ID |
Response
{
"data": { "deleted": true },
"meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
Errors
| Status | Type | Description |
|---|
| 404 | not_found | Credential not found |
