Set Up KnoxCall with Your AI Agent

This page is written to be executed by an AI coding agent. If you’re a human: paste the prompt below into your agent and it can do everything else. If you’re an agent: follow the runbook top to bottom.

For humans — the one-liner

Paste this into Claude Code (or any coding agent with shell access) from inside your project:

Set up KnoxCall for this project. Follow the runbook at
https://docs.knoxcall.com/getting-started/ai-agent-onboarding — create an
account with my email <you@company.com>, proxy this project's outbound API
calls through KnoxCall in Test mode, and show me the verification steps.

Your agent will start the account, then wait for you to do one thing before it can go any further: click the sign-in link KnoxCall emails you. That click is what creates the workspace and releases the agent’s test credential. After that it builds the whole integration against the isolated Test sandbox on its own, and comes back to you once more to approve the switch to Live mode.

For agents — the runbook

Start the signup (one HTTP call, no browser)

POST https://api.knoxcall.com/v1/signup is unauthenticated. It does not return a credential: it returns a claim handle and emails a sign-in link to the owner.

curl -X POST https://api.knoxcall.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@company.com",
    "tenant_name": "Company Name",
    "country": "US"
  }'

The reply is always 202:

{
  "data": {
    "status": "pending",
    "claim_handle": "sck_…",
    "claim_path": "/v1/signup/claim",
    "poll_after_seconds": 5,
    "expires_at": "2026-08-29T09:14:22.117Z"
  }
}

Notes:

Store data.claim_handle. It is a secret — it is what collects the API key — and it is valid for 24 hours.
Omit tenant_slug — the server derives an available one. Don’t iterate on slug collisions yourself.
Rate limit: 3 signups per hour per IP. Do not retry a 4xx.
The reply is identical whether or not the address already has an account. Deliberately: it means this endpoint cannot be used to find out who has a KnoxCall account. It also means a 202 is not proof the workspace will be created — only the click is.

Tell the human to click the link, then poll the claim

Stop and tell the user, in these words: “I’ve started your KnoxCall signup. Click the sign-in link in the email from KnoxCall — that creates your workspace and releases my test credential. I’ll wait.”Then poll, no faster than poll_after_seconds:

curl -X POST https://api.knoxcall.com/v1/signup/claim \
  -H "Content-Type: application/json" \
  -d '{"claim_handle": "sck_…"}'

202 with "status": "pending" — the link has not been clicked yet. Keep waiting; this is a normal success, not an error.
200 with "status": "ready" — the workspace exists. data.starter.api_key.api_key is a one-time plaintext test key. It is never shown again, and a second poll returns 409.
404 — the handle is unknown or expired. Start again at the previous step.

From the 200 response, store these three values now — the key in the user’s secret manager or an untracked .env.local, never in a tracked file:

KNOXCALL_TEST_KEY='tk_…'     # data.starter.api_key.api_key  (the one-time key)
KNOXCALL_KEY_ID='tk_…'       # data.starter.api_key.key_id   (its OAuth client_id)
KNOXCALL_TENANT_SLUG='…'     # data.tenant.slug

The account is on the free plan and the tenant is in Test mode. Everything below works now.

Verify the starter route works

The claim response includes data.starter.curl: two commands that exchange the starter key for a one-hour access token and call a seeded demo route (getting-started, proxying httpbin.org) with it. Run it verbatim — it needs only curl and sed, not jq. A JSON echo from httpbin proves the proxy, your credential, and the tenant are all live.

Discover what to proxy

Scan the project for outbound API calls and their credentials: HTTP client calls (fetch/axios/httpx/requests/Guzzle), base URLs in config, and API keys in .env files. Each distinct upstream API becomes one KnoxCall route; each credential becomes one secret.

Get an access token, then build against the sandbox Management API

The test key itself does not authenticate API calls. Every new workspace is in OAuth-only mode, so Authorization: Bearer tk_… answers 401 use_oauth on the Management API, and the proxy refuses it too. The key is an OAuth client instead: its client_id is KNOXCALL_KEY_ID, and its client_secret is the rest of the key after <key_id>_. Exchange it for a one-hour access token at the sandbox token endpoint — the same exchange data.starter.curl does:

KNOXCALL_CLIENT_SECRET="${KNOXCALL_TEST_KEY#${KNOXCALL_KEY_ID}_}"
TOKEN=$(curl -s -X POST https://sandbox.knoxcall.com/oauth/token \
  -u "$KNOXCALL_KEY_ID:$KNOXCALL_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  | sed -nE 's/.*"access_token" *: *"([^"]+)".*/\1/p')

The token (kc_test_…) lasts expires_in seconds (one hour) and comes with no refresh token. When a call answers 401 with invalid_token, or the hour is up, run the exchange again. Send the tk_ key to the token endpoint and nowhere else.With the token, https://sandbox.knoxcall.com/v1 is the Test-mode Management API. Full reference: API Reference, OpenAPI spec at /api-reference/openapi.yaml. For each upstream API:

# 1. A secret for the upstream's credential
curl -s -X POST https://sandbox.knoxcall.com/v1/secrets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "stripe-api-key", "value": "sk_test_..."}'

# 2. A route to the upstream that injects the secret
ROUTE_ID=$(curl -s -X POST https://sandbox.knoxcall.com/v1/routes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "stripe",
    "target_base_url": "https://api.stripe.com",
    "inject_headers_json": {"Authorization": "Bearer {{secret:stripe-api-key}}"}
  }' \
  | sed -nE 's/.*"id" *: *"([^"]+)".*/\1/p')

# 3. Test mode only: accept calls without a client allowlist, like the seeded
#    getting-started route
curl -s -X PATCH https://sandbox.knoxcall.com/v1/routes/$ROUTE_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"requires_clients": false}'

The injection field is inject_headers_json. POST /v1/routes ignores fields it does not know rather than rejecting them, so a misspelled field such as inject_headers creates a route that injects nothing, and the upstream answers with its own 401.
A new route starts with requires_clients: true: only requests from authorized clients (by IP or mTLS certificate) are accepted, and until one is attached every call answers 403 “No authorized clients are configured”. Attaching a client to a route is done in the dashboard, not through /v1, which is why step 3 turns the allowlist off for the Test route instead. The owner decides the Live setting (last step).
Prefer {{secret_id:UUID}} over {{secret:NAME}} in anything you persist — the UUID is data.id in the secret’s create response. Names break on rename; UUIDs don’t.
The free plan caps how many routes and secrets each mode can hold (the seeded starter route does not count). A create past the cap answers 402 plan_limit: stop and tell the user rather than retrying.

Rewrite the application code

Exactly three changes per integration — see the AI Integration Guide for worked before/after examples and the path-concatenation rules:

Replace the API base URL with https://sandbox-{tenant_slug}.knoxcall.com/api (Test) — the path after the upstream’s base URL stays as-is.
Send Authorization: Bearer <access token> and x-knoxcall-route: <route name>. The application mints its own token with the same client-credentials exchange (client id and secret read from its environment, re-minted before the hour runs out), or uses an SDK, which does that for it. KnoxCall removes its own Authorization header before forwarding and injects the route’s.
Remove the old credential from the code and env files — KnoxCall injects it server-side now.

Check one rewritten call from the shell:

curl -s https://sandbox-$KNOXCALL_TENANT_SLUG.knoxcall.com/api/v1/customers \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-knoxcall-route: stripe"

Routes are identified by the x-knoxcall-route header, not by path matching. Paths concatenate: target_base_url.pathname + request.path. Do not duplicate the base path.x-knoxcall-key: <key> is the legacy way to authenticate a proxy call. It works only in a workspace whose owner has turned OAuth-only mode off, and every new workspace refuses it. Do not write it into new code.

Test end-to-end, then hand off to the human

Run the project’s test suite or exercise the changed call sites. Proxied requests appear in the request log, GET https://sandbox.knoxcall.com/v1/logs with the same Bearer token; configuration changes are in GET https://sandbox.knoxcall.com/v1/audit-logs.Then tell the user, explicitly:

Log in at https://knoxcall.com (the sign-in link they already clicked verified the address and opened the dashboard).
Switch to Live mode, recreate the secrets with production credentials, recreate the routes, and mint a Live API key from API Keys. A Live key is an OAuth client in exactly the same way: the application exchanges it at POST https://api.knoxcall.com/oauth/token, and a Live token calls https://api.knoxcall.com/v1 and the Live proxy host.
On each Live route, attach the application’s servers as authorized clients, or decide deliberately to leave the client allowlist off.
Swap sandbox-{slug} → {slug} in the proxy host, the token endpoint host to api.knoxcall.com, and the test client id and secret for the Live ones — via the environment config, not a code change.

Do not attempt to mint Live keys or move production credentials yourself unless the user explicitly asks.

The same flow with the Node SDK

npm install @knoxcall/sdk. The client takes the key as an OAuth client id and secret, and mints and re-mints the access token itself:

import { signup, claimSignup, KnoxCall } from "@knoxcall/sdk";

const started = await signup({ email: "owner@company.com", tenant_name: "Company Name" });
// …the owner clicks the sign-in link KnoxCall emailed…
let claim = await claimSignup({ claim_handle: started.claim_handle });
while (claim.status === "pending") {
  await new Promise((r) => setTimeout(r, started.poll_after_seconds * 1000));
  claim = await claimSignup({ claim_handle: started.claim_handle });
}
// claim.starter.api_key.api_key is shown exactly once — store it now.
const { key_id, api_key } = claim.starter.api_key;

const knox = new KnoxCall({
  clientId: key_id,
  clientSecret: api_key.slice(key_id.length + 1),
  sandbox: true,
});

await knox.secrets.create({ name: "stripe-api-key", value: process.env.STRIPE_SECRET_KEY! });
const route = await knox.routes.create({ name: "stripe", target_base_url: "https://api.stripe.com" });
await knox.routes.update(route.id, {
  inject_headers_json: { Authorization: "Bearer {{secret:stripe-api-key}}" },
  requires_clients: false, // Test mode only; see the build step above
});

const res = await knox.call("stripe", { path: "/v1/customers" });

Contract summary for tools

What	Value
Signup	`POST https://api.knoxcall.com/v1/signup` — unauthenticated, JSON `{email, tenant_name}` minimum. Always `202` + `claim_handle`; no credential
Claim	`POST https://api.knoxcall.com/v1/signup/claim` — unauthenticated, JSON `{claim_handle}`. `202` until the emailed link is clicked, then `200` once with the test key; `404` unknown or expired, `409` already collected
Credential	The test key is an OAuth client: `client_id` = `data.starter.api_key.key_id`, `client_secret` = the rest of `data.starter.api_key.api_key` after `<key_id>_`. The raw key is accepted only by the token endpoint. Anywhere else it is refused with `401`: `use_oauth` on `/v1`; on the proxy, `This tenant requires OAuth 2.1 tokens` when sent as `x-knoxcall-key`, or `Unauthorized` when sent as `Authorization: Bearer tk_…`
Test token	`POST https://sandbox.knoxcall.com/oauth/token` — HTTP Basic `client_id:client_secret`, form `grant_type=client_credentials`. Returns a one-hour `kc_test_…` `access_token` and no refresh token; re-mint on `401 invalid_token` or expiry
Test Management API	`https://sandbox.knoxcall.com/v1` — `Authorization: Bearer <kc_test_… token>`
Live	`POST https://api.knoxcall.com/oauth/token` with a Live key the owner minted, then `https://api.knoxcall.com/v1` with the `kc_live_…` token
Test proxy host	`https://sandbox-{tenant_slug}.knoxcall.com/api/...`
Live proxy host	`https://{tenant_slug}.knoxcall.com/api/...`
Proxy headers	`Authorization: Bearer <access token>`, `x-knoxcall-route`, optional `x-knoxcall-environment`. `x-knoxcall-key` is legacy: refused unless the owner turned OAuth-only mode off
Route create	`POST /v1/routes` with `name`, `target_base_url`, `inject_headers_json` (unknown fields are ignored, not rejected). A new route has `requires_clients: true`; in Test, `PATCH /v1/routes/{id}` with `{"requires_clients": false}`
SDKs	Node, Python, Go, PHP, Ruby — all export `signup()` and the claim poll (`claimSignup` / `claim_signup` / `ClaimSignup` / `claimSignup`); install commands in SDKs. The Node client takes `clientId` + `clientSecret` and does the token exchange itself
Machine-readable docs	https://docs.knoxcall.com/llms.txt · OpenAPI: `/api-reference/openapi.yaml`

Getting Started

SDKs

Essentials: Routes

Essentials: Ephemeral Proxy

Essentials: Clients

Essentials: Secrets

Essentials: Environments

Essentials: Collections

Essentials: Databases

Essentials: Vaults

Essentials: Inbound Webhooks

Essentials: Rate Limiting

Essentials: Crypto Keys

Essentials: Portable Encryption

Essentials: Certificate Authority

Essentials: Key Management

Essentials: Tenant KMS (BYOK)

Webhooks

Workflows

AI Gateway

Integrations

Integration Setup Guides

Security

Single Sign-On (SAML)

Monitoring

Advanced Features

Infrastructure

Secret Store Migrations

Account

Troubleshooting

Support

About

Set Up KnoxCall with Your AI Agent

For humans — the one-liner

For agents — the runbook

The same flow with the Node SDK

Contract summary for tools

​For humans — the one-liner

​For agents — the runbook

​The same flow with the Node SDK

​Contract summary for tools

For humans — the one-liner

For agents — the runbook

The same flow with the Node SDK

Contract summary for tools