{ "info": { "name": "KnoxCall", "description": "Official KnoxCall API collection. Covers all Client Management API endpoints across Routes, Secrets, Clients, OAuth Clients, Environments, API Keys, Webhooks, Account, Audit Logs, Agents, Crypto Keys, PKI, Vaults, and Dynamic DB Credentials.\n\n## Authentication\nSet KC_CLIENT_ID and KC_CLIENT_SECRET in your environment, then use the Authorization tab at the collection level to fetch an OAuth 2.0 token. Every request inherits the Bearer token automatically.\n\n## Live vs Sandbox\nThe `kc_base` variable controls which environment requests hit:\n- Live: `https://api.knoxcall.com` (default) — requires a standard (`tk_live_…`) API key.\n- Sandbox: `https://sandbox.knoxcall.com` — requires a test (`tk_test_…`) API key, returns isolated test data.\n\nUse the Postman environment files (`KnoxCall-Live.postman_environment.json` / `KnoxCall-Sandbox.postman_environment.json`) to switch between modes — or override `kc_base` directly. Using the wrong key type returns 403 `wrong_key_type`.\n\n## Response envelopes\nEvery `/v1` response uses one of three shapes. The `request_id` in `meta` /\n`error` equals the `X-Request-Id` response header and the server log line — quote\nit in support tickets.\n\n**Success (single resource)**\n```json\n{ \"data\": { \"id\": \"…\" }, \"meta\": { \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\" } }\n```\n\n**Success (list)** — paginated; `meta` carries the page window.\n```json\n{ \"data\": [ … ], \"meta\": { \"total\": 42, \"page\": 1, \"per_page\": 20, \"total_pages\": 3, \"request_id\": \"…\" } }\n```\n\n**Error**\n```json\n{ \"error\": { \"type\": \"validation_error\", \"message\": \"…\", \"request_id\": \"…\" } }\n```\nCommon `type` values: `authentication_required` (401), `forbidden` / `wrong_key_type` (403),\n`not_found` (404), `conflict` (409), `validation_error` (422), `plan_limit` (402),\n`rate_limit_exceeded` (429), `internal_error` (500).\n\n## Pagination\nList endpoints accept `page` (default 1) and `per_page` (default 20, **max 100**;\nhigher values are clamped), plus `sort` and `order` (`asc`/`desc`) where noted per\nendpoint. Read `meta.total` / `meta.total_pages` to iterate.\n\n## Idempotency\nSend an `Idempotency-Key` header (`X-Idempotency-Key` also accepted) on any POST that\ncreates or mints a resource. Replaying the same key returns the original result instead of\ncreating a duplicate.\n\n## Versioning & correlation headers\n- `KnoxCall-Version: 2026-08-05` is returned on every response and identifies the API\n behaviour date. Pin it by sending the same header on requests.\n- `X-Request-Id` is returned on every response (and echoed in the body's `request_id`)\n for end-to-end correlation. Send your own to have it honoured.\n- On `429`, responses also carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`,\n `X-RateLimit-Reset` (unix seconds) and `Retry-After` (seconds).\n\nSaved response examples on representative requests below show these envelopes and headers\nin context.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "_postman_id": "knoxcall-v1" }, "auth": { "type": "oauth2", "oauth2": [ { "key": "tokenName", "value": "KnoxCall", "type": "string" }, { "key": "grant_type", "value": "client_credentials", "type": "string" }, { "key": "accessTokenUrl", "value": "{{kc_base}}/oauth/token", "type": "string" }, { "key": "clientId", "value": "{{KC_CLIENT_ID}}", "type": "string" }, { "key": "clientSecret", "value": "{{KC_CLIENT_SECRET}}", "type": "string" }, { "key": "scope", "value": "", "type": "string" }, { "key": "client_authentication", "value": "header", "type": "string" }, { "key": "addTokenTo", "value": "header", "type": "string" } ] }, "variable": [ { "key": "kc_base", "value": "https://api.knoxcall.com", "type": "string" }, { "key": "route_id", "value": "", "type": "string" }, { "key": "env", "value": "staging", "type": "string" }, { "key": "secret_id", "value": "", "type": "string" }, { "key": "client_id", "value": "", "type": "string" }, { "key": "cred_id", "value": "", "type": "string" }, { "key": "oauth_client_id", "value": "", "type": "string" }, { "key": "environment_id", "value": "", "type": "string" }, { "key": "api_key_id", "value": "", "type": "string" }, { "key": "webhook_id", "value": "", "type": "string" }, { "key": "agent_id", "value": "", "type": "string" }, { "key": "key_name", "value": "", "type": "string" }, { "key": "key_version", "value": "1", "type": "string" }, { "key": "root_name", "value": "", "type": "string" }, { "key": "role_name", "value": "", "type": "string" }, { "key": "vault_name", "value": "", "type": "string" }, { "key": "token_id", "value": "", "type": "string" }, { "key": "connection_name", "value": "", "type": "string" }, { "key": "kc_access_token", "value": "", "type": "string" }, { "key": "workflow_id", "value": "", "type": "string" }, { "key": "execution_id", "value": "", "type": "string" }, { "key": "gateway_id", "value": "", "type": "string" } ], "item": [ { "name": "Auth & OAuth", "description": "OAuth 2.0 discovery, token issuance, introspection, and revocation. All requests in this folder use no auth — they are the auth flow itself.", "item": [ { "name": "Discovery", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{kc_base}}/.well-known/oauth-authorization-server", "host": [ "{{kc_base}}" ], "path": [ ".well-known", "oauth-authorization-server" ] }, "description": "Returns the OAuth 2.0 Authorization Server Metadata document. Consumed automatically by Postman, openid-client, MSAL, and similar libraries." } }, { "name": "Protected Resource Metadata (MCP) — RFC 9728", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{kc_base}}/.well-known/oauth-protected-resource/v1/mcp/{{mcp_slug}}", "host": [ "{{kc_base}}" ], "path": [ ".well-known", "oauth-protected-resource", "v1", "mcp", "{{mcp_slug}}" ] }, "description": "RFC 9728 protected-resource metadata for an MCP server. An MCP client (Claude Code/Desktop) fetches this on a 401 to discover the authorization server and that access tokens must be DPoP-bound, then mints a resource-indicated (RFC 8707) token for exactly this MCP resource." } }, { "name": "Token — client_credentials", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/x-www-form-urlencoded" } ], "body": { "mode": "urlencoded", "urlencoded": [ { "key": "grant_type", "value": "client_credentials" }, { "key": "client_id", "value": "{{KC_CLIENT_ID}}" }, { "key": "client_secret", "value": "{{KC_CLIENT_SECRET}}" } ] }, "url": { "raw": "{{kc_base}}/oauth/token", "host": [ "{{kc_base}}" ], "path": [ "oauth", "token" ] }, "description": "Exchange client credentials for a Bearer access token. The collection-level Authorization tab does this automatically — use this request only if you need the raw token." }, "response": [ { "name": "200 — Access token", "originalRequest": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/x-www-form-urlencoded" } ], "body": { "mode": "urlencoded", "urlencoded": [ { "key": "grant_type", "value": "client_credentials" }, { "key": "client_id", "value": "{{KC_CLIENT_ID}}" }, { "key": "client_secret", "value": "{{KC_CLIENT_SECRET}}" } ] }, "url": { "raw": "{{kc_base}}/oauth/token", "host": [ "{{kc_base}}" ], "path": [ "oauth", "token" ] }, "description": "Exchange client credentials for a Bearer access token. The collection-level Authorization tab does this automatically — use this request only if you need the raw token." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"access_token\": \"eyJhbGciOiJFUzI1NiIsImtpZCI6ImtjXzIwMjYwOCJ9.eyJzdWIiOiJ0ay1saXZlIn0.sig\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600,\n \"scope\": \"secrets:read secrets:write routes:read\"\n}" }, { "name": "401 — invalid_client", "originalRequest": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/x-www-form-urlencoded" } ], "body": { "mode": "urlencoded", "urlencoded": [ { "key": "grant_type", "value": "client_credentials" }, { "key": "client_id", "value": "{{KC_CLIENT_ID}}" }, { "key": "client_secret", "value": "{{KC_CLIENT_SECRET}}" } ] }, "url": { "raw": "{{kc_base}}/oauth/token", "host": [ "{{kc_base}}" ], "path": [ "oauth", "token" ] }, "description": "Exchange client credentials for a Bearer access token. The collection-level Authorization tab does this automatically — use this request only if you need the raw token." }, "status": "Unauthorized", "code": 401, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"error\": \"invalid_client\",\n \"error_description\": \"Client authentication failed (wrong client_id/secret or key type).\"\n}" } ] }, { "name": "Introspect token", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/x-www-form-urlencoded" } ], "body": { "mode": "urlencoded", "urlencoded": [ { "key": "token", "value": "{{kc_access_token}}" } ] }, "url": { "raw": "{{kc_base}}/oauth/introspect", "host": [ "{{kc_base}}" ], "path": [ "oauth", "introspect" ] } } }, { "name": "Revoke token", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/x-www-form-urlencoded" } ], "body": { "mode": "urlencoded", "urlencoded": [ { "key": "token", "value": "{{kc_access_token}}" } ] }, "url": { "raw": "{{kc_base}}/oauth/revoke", "host": [ "{{kc_base}}" ], "path": [ "oauth", "revoke" ] } } }, { "name": "Device authorization (RFC 8628) — start", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/x-www-form-urlencoded" } ], "body": { "mode": "urlencoded", "urlencoded": [ { "key": "client_id", "value": "knoxcall-cli", "description": "Reserved alias — resolves to the tenant's auto-provisioned CLI client at approval time. Real client_ids also accepted." } ] }, "url": { "raw": "{{kc_base}}/oauth/device_authorization", "host": [ "{{kc_base}}" ], "path": [ "oauth", "device_authorization" ] }, "description": "Returns device_code, user_code, verification_uri(_complete), expires_in and interval. The user approves at /oauth/activate in a browser; poll the token endpoint with the device_code grant." } }, { "name": "Token — device_code (poll)", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/x-www-form-urlencoded" } ], "body": { "mode": "urlencoded", "urlencoded": [ { "key": "grant_type", "value": "urn:ietf:params:oauth:grant-type:device_code" }, { "key": "device_code", "value": "{{kc_device_code}}" }, { "key": "client_id", "value": "knoxcall-cli" } ] }, "url": { "raw": "{{kc_base}}/oauth/token", "host": [ "{{kc_base}}" ], "path": [ "oauth", "token" ] }, "description": "Poll at the returned interval. Errors per RFC 8628 §3.5: authorization_pending, slow_down (+5s), expired_token, access_denied. On approval returns tokens plus `tenant` and the real `client_id` extension members." } } ] }, { "name": "Signup", "description": "Headless account creation — the only unauthenticated /v1 endpoint. Designed so scripts and AI agents can onboard without a browser: the response carries a one-time test API key + a seeded Test-mode demo route.", "item": [ { "name": "Create account (headless signup)", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"dev@example.com\",\n \"tenant_name\": \"Acme Inc\",\n \"full_name\": \"Ada Lovelace\",\n \"country\": \"US\"\n}" }, "url": { "raw": "{{kc_base}}/v1/signup", "host": [ "{{kc_base}}" ], "path": [ "v1", "signup" ] }, "description": "Creates a provisional account (email unverified, Free plan) and returns a one-time test API key plus a seeded Test-mode demo route, so the whole integration can be built against sandbox.knoxcall.com before any human steps in. A magic-link email is sent for the owner to verify and open the dashboard. Only on api.knoxcall.com; rate limited to 3/hour/IP. Omit tenant_slug to have the server derive an available one; explicit slugs must be 3-40 chars of lowercase letters, digits and hyphens, and reserved subdomains are rejected." }, "response": [ { "name": "201 — Account created", "originalRequest": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"dev@example.com\",\n \"tenant_name\": \"Acme Inc\",\n \"full_name\": \"Ada Lovelace\",\n \"country\": \"US\"\n}" }, "url": { "raw": "{{kc_base}}/v1/signup", "host": [ "{{kc_base}}" ], "path": [ "v1", "signup" ] }, "description": "Creates a provisional account (email unverified, Free plan) and returns a one-time test API key plus a seeded Test-mode demo route, so the whole integration can be built against sandbox.knoxcall.com before any human steps in. A magic-link email is sent for the owner to verify and open the dashboard. Only on api.knoxcall.com; rate limited to 3/hour/IP. Omit tenant_slug to have the server derive an available one; explicit slugs must be 3-40 chars of lowercase letters, digits and hyphens, and reserved subdomains are rejected." }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"tenant_id\": \"c0ffee00-0000-4a2b-8c3d-000000000000\",\n \"slug\": \"acme\",\n \"admin_url\": \"https://app.knoxcall.com/acme\",\n \"api_key\": {\n \"key_id\": \"kc_key_5d4c3b2a1908\",\n \"api_key\": \"tk_live_5d4c3b2a19080f1e2d3c4b5a69788796\",\n \"key_prefix\": \"tk_live_5d4c3b2a\"\n },\n \"message\": \"Store this API key securely. It will not be shown again.\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] } ] }, { "name": "Routes", "description": "Create and manage proxy routes that forward API requests to upstream targets.", "item": [ { "name": "List routes", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/routes?page=1&per_page=20&sort=created_at&order=desc", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" }, { "key": "sort", "value": "created_at", "description": "created_at | name | enabled" }, { "key": "order", "value": "desc", "description": "asc | desc" }, { "key": "enabled", "value": "", "disabled": true, "description": "true | false" } ] } }, "response": [ { "name": "200 — List (2 routes)", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/routes?page=1&per_page=20&sort=created_at&order=desc", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" }, { "key": "sort", "value": "created_at", "description": "created_at | name | enabled" }, { "key": "order", "value": "desc", "description": "asc | desc" }, { "key": "enabled", "value": "", "disabled": true, "description": "true | false" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-1111-4a2b-8c3d-000000000001\",\n \"name\": \"stripe-payments\",\n \"slug\": \"stripe-payments\",\n \"base_environment\": \"production\",\n \"enabled\": true,\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"updated_at\": \"2026-08-04T14:02:10.000Z\"\n },\n {\n \"id\": \"c0ffee00-1111-4a2b-8c3d-000000000011\",\n \"name\": \"sendgrid-mail\",\n \"slug\": \"sendgrid-mail\",\n \"base_environment\": \"production\",\n \"enabled\": false,\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"updated_at\": \"2026-08-04T14:02:10.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 2,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" }, { "name": "429 — rate_limit_exceeded", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/routes?page=1&per_page=20&sort=created_at&order=desc", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" }, { "key": "sort", "value": "created_at", "description": "created_at | name | enabled" }, { "key": "order", "value": "desc", "description": "asc | desc" }, { "key": "enabled", "value": "", "disabled": true, "description": "true | false" } ] } }, "status": "Too Many Requests", "code": 429, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" }, { "key": "X-RateLimit-Limit", "value": "1000" }, { "key": "X-RateLimit-Remaining", "value": "0" }, { "key": "X-RateLimit-Reset", "value": "1754390400" }, { "key": "Retry-After", "value": "30" } ], "cookie": [], "body": "{\n \"error\": {\n \"type\": \"rate_limit_exceeded\",\n \"message\": \"Too many requests. Retry after 30 seconds.\",\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Get route", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/routes/{{route_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes", "{{route_id}}" ] } }, "response": [ { "name": "200 — Route", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/routes/{{route_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes", "{{route_id}}" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-1111-4a2b-8c3d-000000000001\",\n \"name\": \"stripe-payments\",\n \"slug\": \"stripe-payments\",\n \"base_environment\": \"production\",\n \"enabled\": true,\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"updated_at\": \"2026-08-04T14:02:10.000Z\",\n \"configured_environments\": [\n \"production\",\n \"staging\"\n ],\n \"ip_allowlist\": null,\n \"data_plane_node_id\": null\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" }, { "name": "404 — not_found", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/routes/{{route_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes", "{{route_id}}" ] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"Route not found.\",\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "List Relay field-actions", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/routes/{{route_id}}/actions", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes", "{{route_id}}", "actions" ] }, "description": "List the declarative field-level encrypt/decrypt/tokenize/detokenize actions the proxy applies to this route." } }, { "name": "Create Relay field-action", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"direction\": \"request\",\n \"action\": \"encrypt\",\n \"selectors\": [\"$.card\", \"$.patient.ssn\"],\n \"key_name\": \"relay_key\",\n \"data_role\": \"pci\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/routes/{{route_id}}/actions", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes", "{{route_id}}", "actions" ] }, "description": "Attach a field-action. direction: request|response; action: encrypt|decrypt|tokenize|detokenize; selectors: JSON-path strings (wildcards $.a.* and $.arr[*] supported). key_name is the ecdh key (encrypt/decrypt) or vault (tokenize/detokenize)." } }, { "name": "Delete Relay field-action", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/routes/{{route_id}}/actions/{{action_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes", "{{route_id}}", "actions", "{{action_id}}" ] } } }, { "name": "Create route", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"stripe-payments\",\n \"slug\": \"stripe-payments\",\n \"target_base_url\": \"https://api.stripe.com\",\n \"base_environment\": \"production\",\n \"inject_headers_json\": {\n \"Authorization\": \"Bearer {{STRIPE_SECRET_KEY}}\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/routes", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes" ] } }, "response": [ { "name": "201 — Route created", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"stripe-payments\",\n \"slug\": \"stripe-payments\",\n \"target_base_url\": \"https://api.stripe.com\",\n \"base_environment\": \"production\",\n \"inject_headers_json\": {\n \"Authorization\": \"Bearer {{STRIPE_SECRET_KEY}}\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/routes", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-1111-4a2b-8c3d-000000000001\",\n \"name\": \"stripe-payments\",\n \"slug\": \"stripe-payments\",\n \"base_environment\": \"production\",\n \"enabled\": true,\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"updated_at\": \"2026-08-04T14:02:10.000Z\",\n \"configured_environments\": [\n \"production\",\n \"staging\"\n ],\n \"ip_allowlist\": null,\n \"data_plane_node_id\": null\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" }, { "name": "422 — validation_error", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"stripe-payments\",\n \"slug\": \"stripe-payments\",\n \"target_base_url\": \"https://api.stripe.com\",\n \"base_environment\": \"production\",\n \"inject_headers_json\": {\n \"Authorization\": \"Bearer {{STRIPE_SECRET_KEY}}\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/routes", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes" ] } }, "status": "Unprocessable Entity", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"error\": {\n \"type\": \"validation_error\",\n \"message\": \"slug must be a slug (alphanumeric + _ -, 1-64 chars).\",\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Update route", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"enabled\": true,\n \"rate_limit_enabled\": true,\n \"rate_limit_requests\": 100,\n \"rate_limit_window_sec\": 60\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/routes/{{route_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes", "{{route_id}}" ] } } }, { "name": "Delete route", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/routes/{{route_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes", "{{route_id}}" ] } } }, { "name": "Get route logs", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/routes/{{route_id}}/logs?page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes", "{{route_id}}", "logs" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] } } }, { "name": "List route environments", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/routes/{{route_id}}/environments", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes", "{{route_id}}", "environments" ] } } }, { "name": "Set environment override", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"target_base_url\": \"https://api-staging.stripe.com\",\n \"inject_headers_json\": {\n \"Authorization\": \"Bearer {{STRIPE_TEST_KEY}}\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/routes/{{route_id}}/environments/{{env}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes", "{{route_id}}", "environments", "{{env}}" ] } } }, { "name": "Remove environment override", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/routes/{{route_id}}/environments/{{env}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "routes", "{{route_id}}", "environments", "{{env}}" ] } } } ] }, { "name": "Secrets", "description": "Manage encrypted secrets (API keys, OAuth2 tokens, certificates) that can be injected into route headers and bodies. Secret values are never returned by the API.", "item": [ { "name": "List secrets", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/secrets?page=1&per_page=20&sort=name&order=asc", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" }, { "key": "sort", "value": "name", "description": "created_at | name | base_environment" }, { "key": "order", "value": "asc" } ] } }, "response": [ { "name": "200 — List (2 secrets)", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/secrets?page=1&per_page=20&sort=name&order=asc", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" }, { "key": "sort", "value": "name", "description": "created_at | name | base_environment" }, { "key": "order", "value": "asc" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-2222-4a2b-8c3d-000000000002\",\n \"name\": \"STRIPE_SECRET_KEY\",\n \"secret_type\": \"string\",\n \"base_environment\": \"production\",\n \"strict_expiry_enforcement\": false,\n \"environment_count\": 2,\n \"expires_at\": null,\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"updated_at\": \"2026-08-04T14:02:10.000Z\"\n },\n {\n \"id\": \"c0ffee00-2222-4a2b-8c3d-000000000022\",\n \"name\": \"SENDGRID_API_KEY\",\n \"secret_type\": \"string\",\n \"base_environment\": \"production\",\n \"strict_expiry_enforcement\": false,\n \"environment_count\": 1,\n \"expires_at\": null,\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"updated_at\": \"2026-08-04T14:02:10.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 2,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" }, { "name": "401 — authentication_required", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/secrets?page=1&per_page=20&sort=name&order=asc", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" }, { "key": "sort", "value": "name", "description": "created_at | name | base_environment" }, { "key": "order", "value": "asc" } ] } }, "status": "Unauthorized", "code": 401, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"error\": {\n \"type\": \"authentication_required\",\n \"message\": \"Missing or invalid API key / bearer token.\",\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Get secret", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/secrets/{{secret_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets", "{{secret_id}}" ] } }, "response": [ { "name": "200 - Secret metadata", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/secrets/{{secret_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets", "{{secret_id}}" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-2222-4a2b-8c3d-000000000002\",\n \"name\": \"STRIPE_SECRET_KEY\",\n \"shortcode_name\": \"STRIPE_SECRET_KEY\",\n \"secret_type\": \"string\",\n \"base_environment\": \"production\",\n \"collection_id\": null,\n \"environment_count\": 2,\n \"expires_at\": null,\n \"strict_expiry_enforcement\": false,\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"environments\": [\n {\n \"environment_name\": \"production\",\n \"value_version\": 4,\n \"updated_at\": \"2026-08-04T14:02:10.000Z\",\n \"expires_at_override\": null\n },\n {\n \"environment_name\": \"staging\",\n \"value_version\": 1,\n \"updated_at\": \"2026-08-01T09:15:22.000Z\",\n \"expires_at_override\": \"2026-12-31T00:00:00.000Z\"\n }\n ]\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Create string secret", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"STRIPE_SECRET_KEY\",\n \"value\": \"sk_live_abc123\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/secrets", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets" ] } }, "response": [ { "name": "201 — Secret created", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"STRIPE_SECRET_KEY\",\n \"value\": \"sk_live_abc123\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/secrets", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-2222-4a2b-8c3d-000000000002\",\n \"name\": \"STRIPE_SECRET_KEY\",\n \"secret_type\": \"string\",\n \"base_environment\": \"production\",\n \"strict_expiry_enforcement\": false,\n \"environment_count\": 2,\n \"expires_at\": null,\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"updated_at\": \"2026-08-04T14:02:10.000Z\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" }, { "name": "402 — plan_limit", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"STRIPE_SECRET_KEY\",\n \"value\": \"sk_live_abc123\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/secrets", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets" ] } }, "status": "Payment Required", "code": 402, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"error\": {\n \"type\": \"plan_limit\",\n \"message\": \"Secret limit reached for the current plan. Upgrade to add more.\",\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Create OAuth2 secret", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"secret_type\": \"oauth2\",\n \"name\": \"GOOGLE_OAUTH\",\n \"provider\": \"google\",\n \"client_id\": \"1234567890.apps.googleusercontent.com\",\n \"client_secret\": \"GOCSPX-abc123\",\n \"scopes\": [\"openid\", \"email\", \"profile\"]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/secrets", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets" ] } } }, { "name": "Create certificate secret", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"secret_type\": \"certificate\",\n \"name\": \"MY_TLS_CERT\",\n \"certificate_type\": \"pem\",\n \"certificate_content\": \"-----BEGIN CERTIFICATE-----\\n...\",\n \"private_key\": \"-----BEGIN PRIVATE KEY-----\\n...\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/secrets", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets" ] } } }, { "name": "Update secret value", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"value\": \"sk_live_new_value\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/secrets/{{secret_id}}/value", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets", "{{secret_id}}", "value" ] } }, "response": [ { "name": "200 - Value rotated", "originalRequest": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"value\": \"sk_live_new_value\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/secrets/{{secret_id}}/value", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets", "{{secret_id}}", "value" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-2222-4a2b-8c3d-000000000002\",\n \"name\": \"STRIPE_SECRET_KEY\",\n \"environment\": \"production\",\n \"value_version\": 5\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Get OAuth2 token", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/secrets/{{secret_id}}/oauth2/token", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets", "{{secret_id}}", "oauth2", "token" ] }, "description": "Returns the current access token for an OAuth2 secret. KnoxCall handles refresh automatically." } }, { "name": "Delete secret", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/secrets/{{secret_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "secrets", "{{secret_id}}" ] } } } ] }, { "name": "Clients", "description": "Manage authorized clients (users or servers) with access control. Clients can hold credentials (API keys, mTLS certificates) that authenticate requests through a route.", "item": [ { "name": "List clients", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/clients?page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "clients" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] } }, "response": [ { "name": "200 — List (1 client)", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/clients?page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "clients" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-3333-4a2b-8c3d-000000000003\",\n \"name\": \"my-service\",\n \"description\": \"Backend microservice\",\n \"allowed_ips\": [\n \"10.0.0.0/8\"\n ],\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Get client", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/clients/{{client_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "clients", "{{client_id}}" ] } } }, { "name": "Create client", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"my-service\",\n \"description\": \"Backend microservice\",\n \"allowed_ips\": [\"10.0.0.0/8\"]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/clients", "host": [ "{{kc_base}}" ], "path": [ "v1", "clients" ] } }, "response": [ { "name": "201 — Client created", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"my-service\",\n \"description\": \"Backend microservice\",\n \"allowed_ips\": [\"10.0.0.0/8\"]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/clients", "host": [ "{{kc_base}}" ], "path": [ "v1", "clients" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-3333-4a2b-8c3d-000000000003\",\n \"name\": \"my-service\",\n \"description\": \"Backend microservice\",\n \"allowed_ips\": [\n \"10.0.0.0/8\"\n ],\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Update client", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"description\": \"Updated description\",\n \"enabled\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/clients/{{client_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "clients", "{{client_id}}" ] } } }, { "name": "Delete client", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/clients/{{client_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "clients", "{{client_id}}" ] } } }, { "name": "List credentials", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/clients/{{client_id}}/credentials", "host": [ "{{kc_base}}" ], "path": [ "v1", "clients", "{{client_id}}", "credentials" ] } } }, { "name": "Create credential", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"kind\": \"api_key\",\n \"label\": \"production-key\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/clients/{{client_id}}/credentials", "host": [ "{{kc_base}}" ], "path": [ "v1", "clients", "{{client_id}}", "credentials" ] }, "description": "kind: api_key | mtls_certificate" } }, { "name": "Update credential", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"enabled\": true,\n \"label\": \"updated-label\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/clients/{{client_id}}/credentials/{{cred_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "clients", "{{client_id}}", "credentials", "{{cred_id}}" ] } } }, { "name": "Delete credential", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/clients/{{client_id}}/credentials/{{cred_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "clients", "{{client_id}}", "credentials", "{{cred_id}}" ] } } } ] }, { "name": "OAuth Clients", "description": "Manage OAuth 2.0 client applications that can request tokens from KnoxCall's authorization server.", "item": [ { "name": "List OAuth clients", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/oauth-clients", "host": [ "{{kc_base}}" ], "path": [ "v1", "oauth-clients" ] } }, "response": [ { "name": "200 — List (1 client)", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/oauth-clients", "host": [ "{{kc_base}}" ], "path": [ "v1", "oauth-clients" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-4444-4a2b-8c3d-000000000004\",\n \"client_id\": \"kc_client_7f3a9b2c1d0e\",\n \"name\": \"ci-pipeline\",\n \"grant_types\": [\n \"client_credentials\"\n ],\n \"scopes\": [\n \"secrets:read\",\n \"routes:read\"\n ],\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Get OAuth client", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/oauth-clients/{{oauth_client_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "oauth-clients", "{{oauth_client_id}}" ] } } }, { "name": "Create OAuth client", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"My App\",\n \"type\": \"confidential\",\n \"grant_types\": [\"client_credentials\"],\n \"allowed_scopes\": [\"routes:read\", \"secrets:read\"],\n \"redirect_uris\": []\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/oauth-clients", "host": [ "{{kc_base}}" ], "path": [ "v1", "oauth-clients" ] } }, "response": [ { "name": "201 — OAuth client created (secret shown once)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"My App\",\n \"type\": \"confidential\",\n \"grant_types\": [\"client_credentials\"],\n \"allowed_scopes\": [\"routes:read\", \"secrets:read\"],\n \"redirect_uris\": []\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/oauth-clients", "host": [ "{{kc_base}}" ], "path": [ "v1", "oauth-clients" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-4444-4a2b-8c3d-000000000004\",\n \"client_id\": \"kc_client_7f3a9b2c1d0e\",\n \"name\": \"ci-pipeline\",\n \"grant_types\": [\n \"client_credentials\"\n ],\n \"scopes\": [\n \"secrets:read\",\n \"routes:read\"\n ],\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"client_secret\": \"kc_secret_9a8b7c6d5e4f3021abcdef0123456789\",\n \"message\": \"Store this client secret securely. It will not be shown again.\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Update OAuth client", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"My App v2\",\n \"redirect_uris\": [\"https://myapp.com/callback\"]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/oauth-clients/{{oauth_client_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "oauth-clients", "{{oauth_client_id}}" ] } } }, { "name": "Rotate client secret", "request": { "method": "POST", "url": { "raw": "{{kc_base}}/v1/oauth-clients/{{oauth_client_id}}/rotate-secret", "host": [ "{{kc_base}}" ], "path": [ "v1", "oauth-clients", "{{oauth_client_id}}", "rotate-secret" ] } } }, { "name": "Revoke OAuth client", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/oauth-clients/{{oauth_client_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "oauth-clients", "{{oauth_client_id}}" ] } } } ] }, { "name": "Environments", "description": "Manage deployment environments (e.g. production, staging) that provide per-environment route and secret overrides.", "item": [ { "name": "List environments", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/environments", "host": [ "{{kc_base}}" ], "path": [ "v1", "environments" ] } }, "response": [ { "name": "200 — List (2 environments)", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/environments", "host": [ "{{kc_base}}" ], "path": [ "v1", "environments" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-5555-4a2b-8c3d-000000000005\",\n \"name\": \"staging\",\n \"description\": \"Pre-production environment\",\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n },\n {\n \"id\": \"c0ffee00-5555-4a2b-8c3d-000000000055\",\n \"name\": \"production\",\n \"description\": \"Live traffic\",\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 2,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Create environment", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"staging\",\n \"display_name\": \"Staging\",\n \"description\": \"Pre-production environment\",\n \"color\": \"#F59E0B\",\n \"is_default\": false\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/environments", "host": [ "{{kc_base}}" ], "path": [ "v1", "environments" ] } }, "response": [ { "name": "201 — Environment created", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"staging\",\n \"display_name\": \"Staging\",\n \"description\": \"Pre-production environment\",\n \"color\": \"#F59E0B\",\n \"is_default\": false\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/environments", "host": [ "{{kc_base}}" ], "path": [ "v1", "environments" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-5555-4a2b-8c3d-000000000005\",\n \"name\": \"staging\",\n \"description\": \"Pre-production environment\",\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Update environment", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"display_name\": \"Staging\",\n \"color\": \"#10B981\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/environments/{{environment_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "environments", "{{environment_id}}" ] } } }, { "name": "Delete environment", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/environments/{{environment_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "environments", "{{environment_id}}" ] } } } ] }, { "name": "API Keys", "description": "Create and revoke API keys for programmatic access to the KnoxCall Client Management API. Roles assignable to a key are listed by **List roles**; pass their ids as `role_ids` when creating one.", "item": [ { "name": "List roles", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/roles?subject_kind=api_key&page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "roles" ], "query": [ { "key": "subject_kind", "value": "api_key" }, { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] }, "description": "Read-only role catalog. Use it to find the `role_ids` value for **Create API key**. `Key — Infrastructure` is the role to attach to a Terraform or CI credential: it covers the whole provisioning surface and deliberately excludes secret reveal, custody transitions, workload-identity bindings and the ephemeral proxy.\n\nCreating, editing and deleting roles stays on the admin surface. Requires the `role:list` permission, which all four seeded machine roles carry." }, "response": [ { "name": "200 — Roles assignable to an API key", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/roles?subject_kind=api_key&page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "roles" ], "query": [ { "key": "subject_kind", "value": "api_key" }, { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d\",\n \"name\": \"Key \\u2014 Infrastructure\",\n \"description\": \"For Terraform and other infrastructure-as-code runners.\",\n \"applies_to\": [\n \"api_key\"\n ],\n \"is_default\": false,\n \"seeded\": true\n },\n {\n \"id\": \"c4e2d3f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f\",\n \"name\": \"Key \\u2014 Read-only\",\n \"description\": \"List/read config and analytics/log metadata.\",\n \"applies_to\": [\n \"api_key\"\n ],\n \"is_default\": true,\n \"seeded\": true\n }\n ],\n \"meta\": {\n \"total\": 2,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "List API keys", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/api-keys?page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "api-keys" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] } }, "response": [ { "name": "200 — List (1 key)", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/api-keys?page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "api-keys" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"key_id\": \"kc_key_5d4c3b2a1908\",\n \"name\": \"ci-key\",\n \"key_prefix\": \"tk_live_5d4c3b2a\",\n \"key_type\": \"live\",\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"last_used_at\": \"2026-08-04T14:02:10.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Create API key", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"terraform-prod\",\n \"role_ids\": [\n \"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/api-keys", "host": [ "{{kc_base}}" ], "path": [ "v1", "api-keys" ] }, "description": "The raw API key value is returned only on creation and is never retrievable again.\n\n`role_ids` attaches permission roles in the SAME transaction as the key — list them with `GET /v1/roles?subject_kind=api_key`. A key created with no role is default-denied on every policy-gated endpoint.\n\nA key can never mint a key more privileged than itself: a role granting something the calling key does not hold returns `403 privilege_escalation` naming the offending grant verbatim." }, "response": [ { "name": "200 — API key created (full key shown once)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"terraform-prod\",\n \"role_ids\": [\n \"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/api-keys", "host": [ "{{kc_base}}" ], "path": [ "v1", "api-keys" ] }, "description": "The raw API key value is returned only on creation and is never retrievable again.\n\n`role_ids` attaches permission roles in the SAME transaction as the key — list them with `GET /v1/roles?subject_kind=api_key`. A key created with no role is default-denied on every policy-gated endpoint.\n\nA key can never mint a key more privileged than itself: a role granting something the calling key does not hold returns `403 privilege_escalation` naming the offending grant verbatim." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"f0a1b2c3-d4e5-6f7a-8b9c-0d1e2f3a4b5c\",\n \"key_id\": \"kc_key_5d4c3b2a1908\",\n \"api_key\": \"tk_live_5d4c3b2a19080f1e2d3c4b5a69788796\",\n \"key_prefix\": \"tk_live_5d4c3b2a\",\n \"key_type\": \"standard\",\n \"name\": \"terraform-prod\",\n \"role_ids\": [\n \"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"\n ],\n \"message\": \"Store this API key securely. It will not be shown again.\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" }, { "name": "403 — privilege_escalation (the key-create ceiling)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"terraform-prod\",\n \"role_ids\": [\n \"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/api-keys", "host": [ "{{kc_base}}" ], "path": [ "v1", "api-keys" ] }, "description": "The raw API key value is returned only on creation and is never retrievable again.\n\n`role_ids` attaches permission roles in the SAME transaction as the key — list them with `GET /v1/roles?subject_kind=api_key`. A key created with no role is default-denied on every policy-gated endpoint.\n\nA key can never mint a key more privileged than itself: a role granting something the calling key does not hold returns `403 privilege_escalation` naming the offending grant verbatim." }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"error\": {\n \"type\": \"privilege_escalation\",\n \"message\": \"This API key cannot grant a permission it does not itself hold. Refused grant from role \\\"Key \\u2014 Infrastructure\\\": {\\\"resource_type\\\":\\\"vault\\\",\\\"actions\\\":[\\\"create\\\",\\\"read\\\",\\\"update\\\",\\\"delete\\\",\\\"tokenize\\\",\\\"detokenize\\\"],\\\"effect\\\":\\\"allow\\\"} \\u2014 no rule in your own policy set grants it.\",\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Revoke API key", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/api-keys/{{api_key_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "api-keys", "{{api_key_id}}" ] } } } ] }, { "name": "Webhooks", "description": "Manage webhook subscriptions. KnoxCall signs every delivery with HMAC-SHA256 — verify using the secret_key returned on creation.", "item": [ { "name": "List webhooks", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/webhooks?page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "webhooks" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] } }, "response": [ { "name": "200 — List (1 webhook)", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/webhooks?page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "webhooks" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-6666-4a2b-8c3d-000000000006\",\n \"url\": \"https://example.com/hooks/knoxcall\",\n \"events\": [\n \"secret.created\",\n \"secret.updated\",\n \"route.deleted\"\n ],\n \"enabled\": true,\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Get webhook", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/webhooks/{{webhook_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "webhooks", "{{webhook_id}}" ] } } }, { "name": "Create webhook", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"url\": \"https://my-server.example.com/webhook\",\n \"events\": [\"route.created\", \"route.updated\", \"secret.rotated\"],\n \"enabled\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/webhooks", "host": [ "{{kc_base}}" ], "path": [ "v1", "webhooks" ] }, "description": "The secret_key for signature verification is returned only on creation." }, "response": [ { "name": "201 — Webhook created (signing secret shown once)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"url\": \"https://my-server.example.com/webhook\",\n \"events\": [\"route.created\", \"route.updated\", \"secret.rotated\"],\n \"enabled\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/webhooks", "host": [ "{{kc_base}}" ], "path": [ "v1", "webhooks" ] }, "description": "The secret_key for signature verification is returned only on creation." }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-6666-4a2b-8c3d-000000000006\",\n \"url\": \"https://example.com/hooks/knoxcall\",\n \"events\": [\n \"secret.created\",\n \"secret.updated\",\n \"route.deleted\"\n ],\n \"enabled\": true,\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"signing_secret\": \"whsec_3f2e1d0c9b8a7654fedcba9876543210\",\n \"message\": \"Store this signing secret securely. It will not be shown again.\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Update webhook", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"enabled\": false,\n \"events\": [\"route.created\"]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/webhooks/{{webhook_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "webhooks", "{{webhook_id}}" ] } } }, { "name": "Delete webhook", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/webhooks/{{webhook_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "webhooks", "{{webhook_id}}" ] } } }, { "name": "Get webhook logs", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/webhooks/{{webhook_id}}/logs?page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "webhooks", "{{webhook_id}}", "logs" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] } } }, { "name": "List event types", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/webhooks/event-types", "host": [ "{{kc_base}}" ], "path": [ "v1", "webhooks", "event-types" ] }, "description": "List the webhook event types that can be subscribed to (value, label, description). Includes audit.event (SIEM). Used by connector UIs to populate event dropdowns." }, "response": [ { "name": "200 — Event types", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/webhooks/event-types", "host": [ "{{kc_base}}" ], "path": [ "v1", "webhooks", "event-types" ] }, "description": "List the webhook event types that can be subscribed to (value, label, description). Includes audit.event (SIEM). Used by connector UIs to populate event dropdowns." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"event_types\": [\n {\n \"name\": \"secret.created\",\n \"description\": \"A secret was created.\"\n },\n {\n \"name\": \"secret.updated\",\n \"description\": \"A secret value or metadata changed.\"\n },\n {\n \"name\": \"route.deleted\",\n \"description\": \"A route was deleted.\"\n }\n ]\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Test webhook", "request": { "method": "POST", "url": { "raw": "{{kc_base}}/v1/webhooks/{{webhook_id}}/test", "host": [ "{{kc_base}}" ], "path": [ "v1", "webhooks", "{{webhook_id}}", "test" ] }, "description": "Fire a synthetic webhook.test event at the webhook's configured URL and return delivery status + latency. Delivery goes through the same SSRF-pinned egress and HMAC signing as real events." } } ] }, { "name": "Workflows", "description": "Manage and run workflows. Executions are async; poll GET /v1/workflows/:id/executions or subscribe a webhook to workflow.execution.completed|failed. Execute is idempotent via X-Idempotency-Key.", "item": [ { "name": "List workflows", "request": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/workflows", "host": [ "{{kc_base}}" ], "path": [ "v1", "workflows" ] }, "description": "Paginated: ?page=1&per_page=20." }, "response": [ { "name": "200 — List (1 workflow)", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/workflows", "host": [ "{{kc_base}}" ], "path": [ "v1", "workflows" ] }, "description": "Paginated: ?page=1&per_page=20." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-7777-4a2b-8c3d-000000000007\",\n \"name\": \"rotate-and-notify\",\n \"enabled\": true,\n \"version\": 3,\n \"trigger\": {\n \"type\": \"schedule\",\n \"cron\": \"0 3 * * *\"\n },\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"updated_at\": \"2026-08-04T14:02:10.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Get workflow", "request": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/workflows/{{workflow_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "workflows", "{{workflow_id}}" ] } } }, { "name": "Create workflow", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"My workflow\",\n \"description\": \"Created via API\",\n \"definition\": {\n \"nodes\": [\n {\n \"id\": \"trigger-node\",\n \"type\": \"trigger\",\n \"position\": {\n \"x\": 0,\n \"y\": 0\n },\n \"data\": {\n \"type\": \"trigger\",\n \"label\": \"Manual\",\n \"config\": {\n \"triggerType\": \"manual\"\n }\n }\n }\n ],\n \"edges\": []\n },\n \"enabled\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/workflows", "host": [ "{{kc_base}}" ], "path": [ "v1", "workflows" ] }, "description": "Requires the workflows:write (workflow create) scope." }, "response": [ { "name": "201 — Workflow created", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"My workflow\",\n \"description\": \"Created via API\",\n \"definition\": {\n \"nodes\": [\n {\n \"id\": \"trigger-node\",\n \"type\": \"trigger\",\n \"position\": {\n \"x\": 0,\n \"y\": 0\n },\n \"data\": {\n \"type\": \"trigger\",\n \"label\": \"Manual\",\n \"config\": {\n \"triggerType\": \"manual\"\n }\n }\n }\n ],\n \"edges\": []\n },\n \"enabled\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/workflows", "host": [ "{{kc_base}}" ], "path": [ "v1", "workflows" ] }, "description": "Requires the workflows:write (workflow create) scope." }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-7777-4a2b-8c3d-000000000007\",\n \"name\": \"rotate-and-notify\",\n \"enabled\": true,\n \"version\": 3,\n \"trigger\": {\n \"type\": \"schedule\",\n \"cron\": \"0 3 * * *\"\n },\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"updated_at\": \"2026-08-04T14:02:10.000Z\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Update workflow", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Renamed\",\n \"enabled\": false\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/workflows/{{workflow_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "workflows", "{{workflow_id}}" ] } } }, { "name": "Delete workflow", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{kc_base}}/v1/workflows/{{workflow_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "workflows", "{{workflow_id}}" ] } } }, { "name": "Execute workflow", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"input\": {\n \"example\": \"data\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/workflows/{{workflow_id}}/execute", "host": [ "{{kc_base}}" ], "path": [ "v1", "workflows", "{{workflow_id}}", "execute" ] }, "description": "Queues a run. Send X-Idempotency-Key to make a replay return the same execution." }, "response": [ { "name": "202 — Execution queued", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"input\": {\n \"example\": \"data\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/workflows/{{workflow_id}}/execute", "host": [ "{{kc_base}}" ], "path": [ "v1", "workflows", "{{workflow_id}}", "execute" ] }, "description": "Queues a run. Send X-Idempotency-Key to make a replay return the same execution." }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"execution_id\": \"c0ffee00-e0e0-4a2b-8c3d-0000000000e0\",\n \"workflow_id\": \"c0ffee00-7777-4a2b-8c3d-000000000007\",\n \"status\": \"queued\",\n \"queued_at\": \"2026-08-04T14:02:10.000Z\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "List workflow executions", "request": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/workflows/{{workflow_id}}/executions", "host": [ "{{kc_base}}" ], "path": [ "v1", "workflows", "{{workflow_id}}", "executions" ] }, "description": "Paginated run history — the polling-trigger source." } }, { "name": "Get execution", "request": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/workflows/executions/{{execution_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "workflows", "executions", "{{execution_id}}" ] }, "description": "Execution status + composed step details." } }, { "name": "Cancel execution", "request": { "method": "POST", "header": [], "url": { "raw": "{{kc_base}}/v1/workflows/executions/{{execution_id}}/cancel", "host": [ "{{kc_base}}" ], "path": [ "v1", "workflows", "executions", "{{execution_id}}", "cancel" ] } } } ] }, { "name": "Account", "description": "Retrieve account information and usage metrics.", "item": [ { "name": "Get account", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/account", "host": [ "{{kc_base}}" ], "path": [ "v1", "account" ] } }, "response": [ { "name": "200 — Account", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/account", "host": [ "{{kc_base}}" ], "path": [ "v1", "account" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"tenant_id\": \"c0ffee00-0000-4a2b-8c3d-000000000000\",\n \"slug\": \"acme\",\n \"name\": \"Acme, Inc.\",\n \"plan\": \"growth\",\n \"subscription_status\": \"active\",\n \"created_at\": \"2026-01-14T08:00:00.000Z\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Get usage", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/account/usage", "host": [ "{{kc_base}}" ], "path": [ "v1", "account", "usage" ] } }, "response": [ { "name": "200 — Usage", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/account/usage", "host": [ "{{kc_base}}" ], "path": [ "v1", "account", "usage" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"billing_period\": {\n \"year\": 2026,\n \"month\": 8,\n \"start\": \"2026-08-01T00:00:00.000Z\",\n \"end\": \"2026-09-01T00:00:00.000Z\"\n },\n \"api_calls\": {\n \"used\": 184203,\n \"limit\": 1000000,\n \"percentage\": 18\n },\n \"resources\": {\n \"routes\": {\n \"used\": 12,\n \"limit\": 100\n },\n \"secrets\": {\n \"used\": 47,\n \"limit\": 500\n },\n \"clients\": {\n \"used\": 6,\n \"limit\": 50\n },\n \"environments\": {\n \"used\": 3,\n \"limit\": null\n }\n },\n \"plan\": \"growth\",\n \"status\": \"active\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] } ] }, { "name": "Audit Logs", "description": "Query the immutable audit trail of all API actions taken within your account.", "item": [ { "name": "List audit logs", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/audit-logs?limit=50", "host": [ "{{kc_base}}" ], "path": [ "v1", "audit-logs" ], "query": [ { "key": "limit", "value": "50" }, { "key": "cursor", "value": "", "disabled": true }, { "key": "action", "value": "", "disabled": true, "description": "e.g. route.created" }, { "key": "resource_type", "value": "", "disabled": true, "description": "e.g. route | secret | webhook" } ] } }, "response": [ { "name": "200 — List (2 entries)", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/audit-logs?limit=50", "host": [ "{{kc_base}}" ], "path": [ "v1", "audit-logs" ], "query": [ { "key": "limit", "value": "50" }, { "key": "cursor", "value": "", "disabled": true }, { "key": "action", "value": "", "disabled": true, "description": "e.g. route.created" }, { "key": "resource_type", "value": "", "disabled": true, "description": "e.g. route | secret | webhook" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-1a1a-4a2b-8c3d-00000000a1a1\",\n \"action\": \"secret.create\",\n \"resource_type\": \"secret\",\n \"resource_id\": \"c0ffee00-2222-4a2b-8c3d-000000000002\",\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"ip_address\": \"203.0.113.7\",\n \"ts\": \"2026-08-04T14:02:10.000Z\"\n },\n {\n \"id\": \"c0ffee00-1a1b-4a2b-8c3d-00000000a1a2\",\n \"action\": \"route.update\",\n \"resource_type\": \"route\",\n \"resource_id\": \"c0ffee00-1111-4a2b-8c3d-000000000001\",\n \"request_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n \"ip_address\": \"203.0.113.7\",\n \"ts\": \"2026-08-01T09:15:22.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 2,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] } ] }, { "name": "Agents", "description": "Manage KnoxCall Agents — lightweight daemons that run inside your network to proxy database credentials and capture secrets.", "item": [ { "name": "List agents", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/agents", "host": [ "{{kc_base}}" ], "path": [ "v1", "agents" ] } }, "response": [ { "name": "200 — List (1 agent)", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/agents", "host": [ "{{kc_base}}" ], "path": [ "v1", "agents" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-8888-4a2b-8c3d-000000000008\",\n \"name\": \"deploy-bot\",\n \"status\": \"active\",\n \"fingerprint\": \"a1b2c3d4e5f60718\",\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Create agent", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"prod-db-agent\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/agents", "host": [ "{{kc_base}}" ], "path": [ "v1", "agents" ] } }, "response": [ { "name": "201 — Agent created (one-time enrollment token)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"prod-db-agent\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/agents", "host": [ "{{kc_base}}" ], "path": [ "v1", "agents" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-8888-4a2b-8c3d-000000000008\",\n \"name\": \"deploy-bot\",\n \"status\": \"active\",\n \"fingerprint\": \"a1b2c3d4e5f60718\",\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"enrollment_token\": \"agt_2b3c4d5e6f70819a0b1c2d3e4f506172\",\n \"message\": \"Store this enrollment token securely. It will not be shown again.\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Revoke agent", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/agents/{{agent_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "agents", "{{agent_id}}" ] } } }, { "name": "Get tamper events", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/agents/{{agent_id}}/tamper-events", "host": [ "{{kc_base}}" ], "path": [ "v1", "agents", "{{agent_id}}", "tamper-events" ] } } } ] }, { "name": "Crypto Keys", "description": "Envelope encryption, digital signatures, JWT signing, and webhook signing via named versioned keys. Keys never leave KnoxCall — only ciphertext and signatures are returned.", "item": [ { "name": "List keys", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/crypto/keys", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys" ] } }, "response": [ { "name": "200 — List (1 key)", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/crypto/keys", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-9999-4a2b-8c3d-000000000009\",\n \"name\": \"payments-signing\",\n \"key_type\": \"ecdsa-p256\",\n \"mode\": \"sign\",\n \"current_version\": 1,\n \"deletion_allowed\": false,\n \"description\": \"Signs payment webhooks\",\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"updated_at\": \"2026-08-04T14:02:10.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Get key", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}" ] } } }, { "name": "Create key", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"my-signing-key\",\n \"mode\": \"sign\",\n \"key_type\": \"ed25519\",\n \"description\": \"Signs webhook payloads\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/crypto/keys", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys" ] }, "description": "mode: encrypt | sign | hmac | jwt" }, "response": [ { "name": "201 — Key created", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"my-signing-key\",\n \"mode\": \"sign\",\n \"key_type\": \"ed25519\",\n \"description\": \"Signs webhook payloads\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/crypto/keys", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys" ] }, "description": "mode: encrypt | sign | hmac | jwt" }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-9999-4a2b-8c3d-000000000009\",\n \"name\": \"payments-signing\",\n \"key_type\": \"ecdsa-p256\",\n \"mode\": \"sign\",\n \"current_version\": 1,\n \"deletion_allowed\": false,\n \"description\": \"Signs payment webhooks\",\n \"created_at\": \"2026-08-01T09:15:22.000Z\",\n \"updated_at\": \"2026-08-04T14:02:10.000Z\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Rotate key", "request": { "method": "POST", "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}/rotate", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}", "rotate" ] }, "description": "Generates a new key version. Old versions remain usable for decryption." } }, { "name": "Destroy key version", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}/versions/{{key_version}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}", "versions", "{{key_version}}" ] } } }, { "name": "Get public key", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}/public-key", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}", "public-key" ] } } }, { "name": "Encrypt", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"plaintext\": \"sensitive data\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}/encrypt", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}", "encrypt" ] } }, "response": [ { "name": "200 — Ciphertext", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"plaintext\": \"sensitive data\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}/encrypt", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}", "encrypt" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"ciphertext\": \"kc:v1:payments-signing:1:Zm9vYmFyYmF6cXV4Y2lwaGVydGV4dGV4YW1wbGU=\",\n \"key\": \"payments-signing\",\n \"key_version\": 1\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Decrypt", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"ciphertext\": \"vault:v1:base64encodedciphertext\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}/decrypt", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}", "decrypt" ] } }, "response": [ { "name": "200 — Plaintext", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"ciphertext\": \"vault:v1:base64encodedciphertext\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}/decrypt", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}", "decrypt" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"plaintext\": \"hello world\",\n \"key_version\": 1\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Rewrap", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"ciphertext\": \"vault:v1:base64encodedciphertext\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}/rewrap", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}", "rewrap" ] }, "description": "Re-encrypts ciphertext under the latest key version without exposing the plaintext." } }, { "name": "Encrypt Data (portable kc:)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"data\": {\n \"card\": \"4242424242424242\",\n \"ssn\": \"123-45-6789\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/encrypt", "host": [ "{{kc_base}}" ], "path": [ "v1", "encrypt" ] }, "description": "Structure-preserving public-key encryption. Returns the same JSON shape with every scalar leaf replaced by a portable, self-describing `kc:` ciphertext string you can store anywhere. Optional body fields: `key` (named ecdh-p256 key; defaults to an auto-provisioned key) and `role` (data-role bound into the ciphertext)." } }, { "name": "Decrypt Data (portable kc:)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"data\": {\n \"card\": \"kc:1:s:...:$\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/decrypt", "host": [ "{{kc_base}}" ], "path": [ "v1", "decrypt" ] }, "description": "Inverse of /v1/encrypt. Every `kc:` string leaf is decrypted in place; non-`kc:` values pass through untouched. Pass `role` if the values were encrypted under a data-role." } }, { "name": "Inspect (portable kc:)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"value\": \"kc:1:s:...:$\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/inspect", "host": [ "{{kc_base}}" ], "path": [ "v1", "inspect" ] }, "description": "Returns metadata about a `kc:` ciphertext (scheme, version, datatype, key reference, fingerprint) WITHOUT decrypting it." } }, { "name": "Mint Client Capability Token", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"action\": \"decrypt\",\n \"data\": \"kc:1:s:...:$\",\n \"ttl_seconds\": 300\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/client-tokens", "host": [ "{{kc_base}}" ], "path": [ "v1", "client-tokens" ] }, "description": "Backend (API-key authenticated) mints a single-use, payload-pinned capability token bound to ONE ciphertext (`action: decrypt`) or vault token (`action: detokenize`). Hand the returned `token` to a browser so it can reveal exactly that value once, without an API key." } }, { "name": "Client Decrypt (capability token)", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{client_capability_token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"data\": \"kc:1:s:...:$\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/client/decrypt", "host": [ "{{kc_base}}" ], "path": [ "v1", "client", "decrypt" ] }, "description": "Browser-side: exchange a `kct_` capability token (Authorization: Bearer) for the plaintext of the bound `kc:` ciphertext. Single-use; the token is consumed on success." } }, { "name": "Client Detokenize (capability token)", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{client_capability_token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"data\": \"tok_...\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/client/detokenize", "host": [ "{{kc_base}}" ], "path": [ "v1", "client", "detokenize" ] }, "description": "Browser-side: exchange a `kct_` capability token for the value behind the bound vault token. Single-use." } }, { "name": "Sign", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"data\": \"message to sign\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}/sign", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}", "sign" ] } } }, { "name": "Verify", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"data\": \"message to sign\",\n \"signature\": \"base64signature\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}/verify", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}", "verify" ] } } }, { "name": "Sign JWT", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"claims\": {\n \"sub\": \"user-123\",\n \"aud\": \"my-service\",\n \"exp\": 9999999999\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}/sign-jwt", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}", "sign-jwt" ] } } }, { "name": "Verify JWT", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"token\": \"eyJhbGciOiJFZERTQSJ9...\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}/verify-jwt", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}", "verify-jwt" ] } } }, { "name": "Sign webhook payload", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"payload\": \"{\\\"event\\\": \\\"order.created\\\", \\\"id\\\": \\\"ord_123\\\"}\",\n \"format\": \"knoxcall-v1\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/crypto/keys/{{key_name}}/sign-webhook", "host": [ "{{kc_base}}" ], "path": [ "v1", "crypto", "keys", "{{key_name}}", "sign-webhook" ] } } } ] }, { "name": "PKI / Certificate Authority", "description": "KnoxCall's built-in Certificate Authority. Create private roots, issue short-lived leaf certificates, and manage revocation.", "item": [ { "name": "List roots", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/pki/roots", "host": [ "{{kc_base}}" ], "path": [ "v1", "pki", "roots" ] } }, "response": [ { "name": "200 — List (1 root)", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/pki/roots", "host": [ "{{kc_base}}" ], "path": [ "v1", "pki", "roots" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-bbbb-4a2b-8c3d-00000000000b\",\n \"name\": \"internal-root\",\n \"common_name\": \"KnoxCall Internal Root CA\",\n \"not_after\": \"2036-08-01T00:00:00.000Z\",\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Create root", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"internal-ca\",\n \"subject\": {\n \"common_name\": \"Internal CA\",\n \"organization\": \"Acme Corp\",\n \"country\": \"US\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/pki/roots", "host": [ "{{kc_base}}" ], "path": [ "v1", "pki", "roots" ] } } }, { "name": "Get root certificate (PEM)", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/pki/roots/{{root_name}}/cert", "host": [ "{{kc_base}}" ], "path": [ "v1", "pki", "roots", "{{root_name}}", "cert" ] } } }, { "name": "Rotate intermediate", "request": { "method": "POST", "url": { "raw": "{{kc_base}}/v1/pki/roots/{{root_name}}/rotate-intermediate", "host": [ "{{kc_base}}" ], "path": [ "v1", "pki", "roots", "{{root_name}}", "rotate-intermediate" ] } } }, { "name": "Get CRL", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/pki/roots/{{root_name}}/crl", "host": [ "{{kc_base}}" ], "path": [ "v1", "pki", "roots", "{{root_name}}", "crl" ] } } }, { "name": "List roles", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/pki/roots/{{root_name}}/roles", "host": [ "{{kc_base}}" ], "path": [ "v1", "pki", "roots", "{{root_name}}", "roles" ] } } }, { "name": "Create role", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"role_name\": \"internal-services\",\n \"allowed_domains\": [\"internal.example.com\"],\n \"allow_subdomains\": true,\n \"max_ttl_seconds\": 86400,\n \"default_ttl_seconds\": 3600\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/pki/roots/{{root_name}}/roles", "host": [ "{{kc_base}}" ], "path": [ "v1", "pki", "roots", "{{root_name}}", "roles" ] } } }, { "name": "Issue certificate", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"subject\": { \"common_name\": \"api.internal.example.com\" },\n \"san_dns\": [\"api.internal.example.com\"],\n \"ttl_seconds\": 3600\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/pki/roots/{{root_name}}/roles/{{role_name}}/issue", "host": [ "{{kc_base}}" ], "path": [ "v1", "pki", "roots", "{{root_name}}", "roles", "{{role_name}}", "issue" ] } }, "response": [ { "name": "200 — Certificate issued", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"subject\": { \"common_name\": \"api.internal.example.com\" },\n \"san_dns\": [\"api.internal.example.com\"],\n \"ttl_seconds\": 3600\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/pki/roots/{{root_name}}/roles/{{role_name}}/issue", "host": [ "{{kc_base}}" ], "path": [ "v1", "pki", "roots", "{{root_name}}", "roles", "{{role_name}}", "issue" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"serial_hex\": \"1a2b3c4d5e6f70819a0b1c2d3e4f5061\",\n \"certificate\": \"-----BEGIN CERTIFICATE-----\\nMIIB...leaf...IDAQAB\\n-----END CERTIFICATE-----\",\n \"issuing_ca\": \"-----BEGIN CERTIFICATE-----\\nMIIB...intermediate...IDAQAB\\n-----END CERTIFICATE-----\",\n \"private_key\": \"-----BEGIN PRIVATE KEY-----\\nMIGH...key...==\\n-----END PRIVATE KEY-----\",\n \"not_before\": \"2026-08-04T14:02:10.000Z\",\n \"not_after\": \"2026-09-03T14:02:10.000Z\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Revoke certificate", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"serial_hex\": \"4a:bc:12:...\",\n \"reason\": \"superseded\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/pki/roots/{{root_name}}/revoke", "host": [ "{{kc_base}}" ], "path": [ "v1", "pki", "roots", "{{root_name}}", "revoke" ] } } } ] }, { "name": "Vaults", "description": "Data tokenization vaults. Store sensitive values (card numbers, SSNs, PII) as format-preserving tokens. Values never leave KnoxCall in plaintext.", "item": [ { "name": "List vaults", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/vaults?limit=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults" ], "query": [ { "key": "limit", "value": "20" }, { "key": "cursor", "value": "", "disabled": true } ] } }, "response": [ { "name": "200 — List (1 vault)", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/vaults?limit=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults" ], "query": [ { "key": "limit", "value": "20" }, { "key": "cursor", "value": "", "disabled": true } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-aaaa-4a2b-8c3d-00000000000a\",\n \"name\": \"card-vault\",\n \"token_format\": \"fpe_pan\",\n \"custody_mode\": \"knoxcall\",\n \"crypto_key_id\": \"c0ffee00-9999-4a2b-8c3d-000000000009\",\n \"default_ttl_seconds\": null,\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Get vault", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/vaults/{{vault_name}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults", "{{vault_name}}" ] } } }, { "name": "Create vault", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"pci-cards\",\n \"token_format\": \"preserve\",\n \"default_ttl_seconds\": 2592000,\n \"description\": \"Payment card tokenization vault\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/vaults", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults" ] } }, "response": [ { "name": "201 — Vault created", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"pci-cards\",\n \"token_format\": \"preserve\",\n \"default_ttl_seconds\": 2592000,\n \"description\": \"Payment card tokenization vault\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/vaults", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-aaaa-4a2b-8c3d-00000000000a\",\n \"name\": \"card-vault\",\n \"token_format\": \"fpe_pan\",\n \"custody_mode\": \"knoxcall\",\n \"crypto_key_id\": \"c0ffee00-9999-4a2b-8c3d-000000000009\",\n \"default_ttl_seconds\": null,\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Update vault", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"description\": \"Updated description\",\n \"default_ttl_seconds\": 86400,\n \"enabled\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/vaults/{{vault_name}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults", "{{vault_name}}" ] } } }, { "name": "Delete vault", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/vaults/{{vault_name}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults", "{{vault_name}}" ] } } }, { "name": "Rotate vault key", "request": { "method": "POST", "url": { "raw": "{{kc_base}}/v1/vaults/{{vault_name}}/rotate", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults", "{{vault_name}}", "rotate" ] } } }, { "name": "Tokenize", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"value\": \"4111111111111111\",\n \"metadata\": { \"card_type\": \"visa\", \"last4\": \"1111\" },\n \"ttl_seconds\": 2592000\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/vaults/{{vault_name}}/tokenize", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults", "{{vault_name}}", "tokenize" ] } }, "response": [ { "name": "200 — Token", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"value\": \"4111111111111111\",\n \"metadata\": { \"card_type\": \"visa\", \"last4\": \"1111\" },\n \"ttl_seconds\": 2592000\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/vaults/{{vault_name}}/tokenize", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults", "{{vault_name}}", "tokenize" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"tok_9f8e7d6c5b4a3928\",\n \"token\": \"4111-1111-1111-8342\",\n \"vault_name\": \"card-vault\",\n \"token_format\": \"fpe_pan\",\n \"expires_at\": null,\n \"created_at\": \"2026-08-04T14:02:10.000Z\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Bulk tokenize", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"values\": [\n { \"value\": \"4111111111111111\" },\n { \"value\": \"5500005555555559\" },\n { \"value\": \"4222222222222\" }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/vaults/{{vault_name}}/tokenize-bulk", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults", "{{vault_name}}", "tokenize-bulk" ] } } }, { "name": "List tokens", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/vaults/{{vault_name}}/tokens?limit=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults", "{{vault_name}}", "tokens" ], "query": [ { "key": "limit", "value": "20" }, { "key": "cursor", "value": "", "disabled": true } ] } } }, { "name": "Detokenize", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/vaults/{{vault_name}}/tokens/{{token_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults", "{{vault_name}}", "tokens", "{{token_id}}" ] }, "description": "Returns the token and its plaintext value. Requires elevated scope." } }, { "name": "Update token metadata", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"metadata\": { \"card_type\": \"visa\", \"billing_zip\": \"10001\" }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/vaults/{{vault_name}}/tokens/{{token_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults", "{{vault_name}}", "tokens", "{{token_id}}" ] } } }, { "name": "Delete token", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/vaults/{{vault_name}}/tokens/{{token_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "vaults", "{{vault_name}}", "tokens", "{{token_id}}" ] } } } ] }, { "name": "Wrap Credentials", "description": "Escrow a third-party provider key into KnoxCall custody, host-pinned. The ephemeral proxy injects it under X-Knox-Upstream-Auth-Secret only for hosts in allowed_hosts.", "item": [ { "name": "Escrow provider credential", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"provider\": \"stripe\",\n \"name\": \"wrap-stripe-live\",\n \"value\": \"sk_live_abc123\",\n \"hosts\": [\n \"api.stripe.com\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/wrap/credentials", "host": [ "{{kc_base}}" ], "path": [ "v1", "wrap", "credentials" ] }, "description": "Store the provider key envelope-encrypted and bind it to allowed_hosts. The value is sent once and never returned." }, "response": [ { "name": "200 — Credential escrowed", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"provider\": \"stripe\",\n \"name\": \"wrap-stripe-live\",\n \"value\": \"sk_live_abc123\",\n \"hosts\": [\n \"api.stripe.com\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/wrap/credentials", "host": [ "{{kc_base}}" ], "path": [ "v1", "wrap", "credentials" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"secret_id\": \"c0ffee00-2222-4a2b-8c3d-000000000009\",\n \"name\": \"wrap-stripe-live\",\n \"provider\": \"stripe\",\n \"allowed_hosts\": [\n \"api.stripe.com\"\n ],\n \"sandbox\": false\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" }, { "name": "409 — conflict (name exists)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"provider\": \"stripe\",\n \"name\": \"wrap-stripe-live\",\n \"value\": \"sk_live_abc123\",\n \"hosts\": [\n \"api.stripe.com\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/wrap/credentials", "host": [ "{{kc_base}}" ], "path": [ "v1", "wrap", "credentials" ] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" } ], "cookie": [], "body": "{\n \"error\": {\n \"type\": \"conflict\",\n \"message\": \"A secret named 'wrap-stripe-live' already exists.\",\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] } ] }, { "name": "Opportunities", "description": "Promotion suggestions (agent-observed + gateway-traffic). GET refreshes gateway detection on read; accept promotes to a route + secret binding.", "item": [ { "name": "List opportunities", "request": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/opportunities", "host": [ "{{kc_base}}" ], "path": [ "v1", "opportunities" ] }, "description": "Refreshes gateway-traffic detection for the current space, then lists both sources." } }, { "name": "Accept (promote to a route)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{kc_base}}/v1/opportunities/{{opportunity_id}}/accept", "host": [ "{{kc_base}}" ], "path": [ "v1", "opportunities", "{{opportunity_id}}", "accept" ] }, "description": "Promotes a gateway suggestion to a durable route + secret binding. Auto-binds an escrowed wrap credential for the host, or pass \"secret\".", "body": { "mode": "raw", "raw": "{\n \"collection_name\": \"Wrapped APIs\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Dismiss", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{kc_base}}/v1/opportunities/{{opportunity_id}}/dismiss", "host": [ "{{kc_base}}" ], "path": [ "v1", "opportunities", "{{opportunity_id}}", "dismiss" ] }, "description": "Closes a pending suggestion.", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "Dynamic DB Credentials", "description": "Manage database connections and issue short-lived credential leases. The KnoxCall Agent handles the actual DB proxy inside your network.", "item": [ { "name": "List connections", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/dyn-db-credentials", "host": [ "{{kc_base}}" ], "path": [ "v1", "dyn-db-credentials" ] } }, "response": [ { "name": "200 — List (1 connection)", "originalRequest": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/dyn-db-credentials", "host": [ "{{kc_base}}" ], "path": [ "v1", "dyn-db-credentials" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-cccc-4a2b-8c3d-00000000000c\",\n \"name\": \"analytics-pg\",\n \"engine\": \"postgres\",\n \"execution_mode\": \"cloud\",\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Get connection", "request": { "method": "GET", "url": { "raw": "{{kc_base}}/v1/dyn-db-credentials/{{connection_name}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "dyn-db-credentials", "{{connection_name}}" ] } } }, { "name": "Create connection", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"prod-postgres\",\n \"engine\": \"postgres\",\n \"host\": \"db.internal.example.com\",\n \"port\": 5432,\n \"database_name\": \"mydb\",\n \"admin_username\": \"knoxcall_admin\",\n \"admin_password\": \"supersecret\",\n \"default_ttl_seconds\": 3600,\n \"max_ttl_seconds\": 86400\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/dyn-db-credentials", "host": [ "{{kc_base}}" ], "path": [ "v1", "dyn-db-credentials" ] }, "description": "engine: postgres | mysql | mssql | mongodb" } }, { "name": "Update connection", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"default_ttl_seconds\": 1800\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/dyn-db-credentials/{{connection_name}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "dyn-db-credentials", "{{connection_name}}" ] } } }, { "name": "Delete connection", "request": { "method": "DELETE", "url": { "raw": "{{kc_base}}/v1/dyn-db-credentials/{{connection_name}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "dyn-db-credentials", "{{connection_name}}" ] } } }, { "name": "Rotate SSH key", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"ssh_private_key\": \"-----BEGIN OPENSSH PRIVATE KEY-----\\n...\",\n \"ssh_host_fingerprint\": \"SHA256:...\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/dyn-db-credentials/{{connection_name}}/rotate-ssh-key", "host": [ "{{kc_base}}" ], "path": [ "v1", "dyn-db-credentials", "{{connection_name}}", "rotate-ssh-key" ] } } }, { "name": "Issue credential lease", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"ttl_seconds\": 3600\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/dyn-db-credentials/{{connection_name}}/lease", "host": [ "{{kc_base}}" ], "path": [ "v1", "dyn-db-credentials", "{{connection_name}}", "lease" ] }, "description": "Issues a short-lived username/password pair. The KnoxCall Agent creates the DB user and revokes it when the lease expires." }, "response": [ { "name": "200 — Credential lease (password shown once)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"ttl_seconds\": 3600\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/dyn-db-credentials/{{connection_name}}/lease", "host": [ "{{kc_base}}" ], "path": [ "v1", "dyn-db-credentials", "{{connection_name}}", "lease" ] }, "description": "Issues a short-lived username/password pair. The KnoxCall Agent creates the DB user and revokes it when the lease expires." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"lease_id\": 4821,\n \"username\": \"v-analytics-r-7f3a9b2c\",\n \"password\": \"A9x!2kQ7-mZ4pL0w\",\n \"connection_name\": \"analytics-pg\",\n \"role_name\": \"readonly\",\n \"expires_at\": \"2026-08-05T15:02:10.000Z\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] } ] }, { "name": "AI Gateway", "description": "KnoxCall AI Gateway control plane — provision gateways, agents, and agent tokens, and read usage. Single responses return {data, meta}; list responses return {data:[...], meta:{total, page, per_page, total_pages, request_id}} and accept ?page & ?per_page. Auth: a management API key (tk_live_…) or an OAuth Bearer token; the ai_gateway scope gates access (read for list/get, write for create/update/delete, mint for minting tokens). The AI data plane (POST /v1/ai//...) is a SEPARATE surface documented in the AI reference.", "item": [ { "name": "Gateways", "description": "Gateways are the top-level container for AI egress. Each gateway holds agents and optional daily/monthly USD budgets. Requires the ai_gateway scope (read to list/get, write to create/update/delete).", "item": [ { "name": "List gateways", "request": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/ai-gateway/gateways?page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "gateways" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] }, "description": "Paginated: ?page=1&per_page=20. Requires ai_gateway read scope." }, "response": [ { "name": "200 — List (1 gateway)", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/ai-gateway/gateways?page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "gateways" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] }, "description": "Paginated: ?page=1&per_page=20. Requires ai_gateway read scope." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"c0ffee00-dddd-4a2b-8c3d-00000000000d\",\n \"name\": \"prod-ai\",\n \"slug\": \"prod-ai\",\n \"status\": \"active\",\n \"upstreams\": [\n \"anthropic\",\n \"openai\"\n ],\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"page\": 1,\n \"per_page\": 20,\n \"total_pages\": 1,\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Create gateway", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Production AI Gateway\",\n \"slug\": \"prod-ai-gateway\",\n \"description\": \"Primary AI egress gateway\",\n \"budget_daily_usd\": 50,\n \"budget_monthly_usd\": 1000\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/ai-gateway/gateways", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "gateways" ] }, "description": "Requires ai_gateway write scope." }, "response": [ { "name": "201 — Gateway created", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Production AI Gateway\",\n \"slug\": \"prod-ai-gateway\",\n \"description\": \"Primary AI egress gateway\",\n \"budget_daily_usd\": 50,\n \"budget_monthly_usd\": 1000\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/ai-gateway/gateways", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "gateways" ] }, "description": "Requires ai_gateway write scope." }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"c0ffee00-dddd-4a2b-8c3d-00000000000d\",\n \"name\": \"prod-ai\",\n \"slug\": \"prod-ai\",\n \"status\": \"active\",\n \"upstreams\": [\n \"anthropic\",\n \"openai\"\n ],\n \"created_at\": \"2026-08-01T09:15:22.000Z\"\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Get gateway", "request": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/ai-gateway/gateways/{{gateway_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "gateways", "{{gateway_id}}" ] }, "description": "Requires ai_gateway read scope." } }, { "name": "Update gateway", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Production AI Gateway (renamed)\",\n \"description\": \"Updated description\",\n \"budget_daily_usd\": 75,\n \"budget_monthly_usd\": 1500\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/ai-gateway/gateways/{{gateway_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "gateways", "{{gateway_id}}" ] }, "description": "Requires ai_gateway write scope." } }, { "name": "Delete gateway", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{kc_base}}/v1/ai-gateway/gateways/{{gateway_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "gateways", "{{gateway_id}}" ] }, "description": "Returns {id, status}. Requires ai_gateway write scope." } } ] }, { "name": "Agents", "description": "Agents belong to a gateway and define model policy (default model, allow/deny lists), routing, budgets, streaming, and firewall/PII redaction policies. The agent slug is used on the data plane: POST /v1/ai//... Requires the ai_gateway scope (read to list/get, write to create/update/delete).", "item": [ { "name": "List agents", "request": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/ai-gateway/gateways/{{gateway_id}}/agents?page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "gateways", "{{gateway_id}}", "agents" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] }, "description": "Agents under a gateway. Paginated: ?page=1&per_page=20. Requires ai_gateway read scope." } }, { "name": "Create agent", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Support Copilot\",\n \"slug\": \"support-copilot\",\n \"description\": \"Customer support assistant\",\n \"primary_route_id\": \"{{route_id}}\",\n \"default_model\": \"claude-sonnet-5\",\n \"model_allowlist\": [\n \"claude-sonnet-5\",\n \"claude-opus-4-8\"\n ],\n \"model_denylist\": [],\n \"budget_daily_usd\": 10,\n \"budget_monthly_usd\": 200,\n \"streaming_enabled\": true,\n \"firewall_policy_id\": null,\n \"pii_redact_policy_id\": null\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/ai-gateway/gateways/{{gateway_id}}/agents", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "gateways", "{{gateway_id}}", "agents" ] }, "description": "Requires ai_gateway write scope." } }, { "name": "Get agent", "request": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/ai-gateway/agents/{{agent_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "agents", "{{agent_id}}" ] }, "description": "Requires ai_gateway read scope." } }, { "name": "Update agent", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Support Copilot (v2)\",\n \"default_model\": \"claude-opus-4-8\",\n \"streaming_enabled\": false,\n \"budget_daily_usd\": 25\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/ai-gateway/agents/{{agent_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "agents", "{{agent_id}}" ] }, "description": "Any create field may be patched. Requires ai_gateway write scope." } }, { "name": "Delete agent", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{kc_base}}/v1/ai-gateway/agents/{{agent_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "agents", "{{agent_id}}" ] }, "description": "Returns {id, status}. Requires ai_gateway write scope." } } ] }, { "name": "Tokens", "description": "Agent tokens authenticate data-plane AI calls. The plaintext token is returned ONCE at mint time and is never retrievable again. DPoP-bound tokens require a dpop_jkt. A test (tk_test_) key mints test-env tokens server-side — there is no env parameter.", "item": [ { "name": "List agent tokens", "request": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/ai-gateway/agents/{{agent_id}}/tokens?page=1&per_page=20", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "agents", "{{agent_id}}", "tokens" ], "query": [ { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" } ] }, "description": "Paginated: ?page=1&per_page=20. Never returns plaintext. Requires ai_gateway read scope." } }, { "name": "Mint agent token", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"ci-runner-token\",\n \"kind\": \"agent\",\n \"dpop_required\": false,\n \"expires_in_seconds\": 2592000\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{kc_base}}/v1/ai-gateway/agents/{{agent_id}}/tokens", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "agents", "{{agent_id}}", "tokens" ] }, "description": "Returns data {id, name, kind, prefix, token, dpop_required, expires_at}. kind is one of agent|read|tool|oneshot. The token field is plaintext and shown ONCE. Set dpop_required=true only together with a dpop_jkt. Requires ai_gateway mint scope." } }, { "name": "Revoke agent token", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{kc_base}}/v1/ai-gateway/agents/{{agent_id}}/tokens/{{token_id}}", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "agents", "{{agent_id}}", "tokens", "{{token_id}}" ] }, "description": "Returns {id, revoked:true}. Requires ai_gateway write scope." } } ] }, { "name": "Usage", "description": "Aggregated model usage and cost, grouped by provider/model over a 7d/30d/90d window, optionally filtered to a single agent. Requires the ai_gateway read scope.", "item": [ { "name": "Get usage", "request": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/ai-gateway/usage?period=7d", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "usage" ], "query": [ { "key": "period", "value": "7d" }, { "key": "agent_id", "value": "{{agent_id}}", "disabled": true } ] }, "description": "period = 7d|30d|90d (default 7d). Optional agent_id filters to one agent. Returns data {period_days, by_model:[{provider, model, requests, input_tokens, output_tokens, cost_usd, unpriced_requests}], totals:{...}}. Requires ai_gateway read scope." }, "response": [ { "name": "200 — Usage summary", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{kc_base}}/v1/ai-gateway/usage?period=7d", "host": [ "{{kc_base}}" ], "path": [ "v1", "ai-gateway", "usage" ], "query": [ { "key": "period", "value": "7d" }, { "key": "agent_id", "value": "{{agent_id}}", "disabled": true } ] }, "description": "period = 7d|30d|90d (default 7d). Optional agent_id filters to one agent. Returns data {period_days, by_model:[{provider, model, requests, input_tokens, output_tokens, cost_usd, unpriced_requests}], totals:{...}}. Requires ai_gateway read scope." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "550e8400-e29b-41d4-a716-446655440000" }, { "key": "KnoxCall-Version", "value": "2026-08-05" } ], "cookie": [], "body": "{\n \"data\": {\n \"period_days\": 30,\n \"by_model\": [\n {\n \"provider\": \"anthropic\",\n \"model\": \"claude-sonnet-5\",\n \"requests\": 1420,\n \"input_tokens\": 3820114,\n \"output_tokens\": 981233,\n \"cost_usd\": 42.18,\n \"unpriced_requests\": 0\n },\n {\n \"provider\": \"openai\",\n \"model\": \"gpt-4o\",\n \"requests\": 310,\n \"input_tokens\": 512300,\n \"output_tokens\": 128740,\n \"cost_usd\": 9.06,\n \"unpriced_requests\": 2\n }\n ],\n \"totals\": {\n \"requests\": 1730,\n \"input_tokens\": 4332414,\n \"output_tokens\": 1109973,\n \"cost_usd\": 51.24,\n \"unpriced_requests\": 2\n }\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}" } ] }, { "name": "Export usage (FinOps)", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/ai-gateway/usage/export?group_by=team&period=30d&format=json", "host": [ "{{base_url}}" ], "path": [ "v1", "ai-gateway", "usage", "export" ], "query": [ { "key": "group_by", "value": "team", "description": "user | team | agent | model | provider | tag:" }, { "key": "period", "value": "30d", "description": "7d | 30d | 90d" }, { "key": "format", "value": "json", "description": "json | csv" } ] }, "description": "Aggregated spend grouped by the chosen dimension (showback/chargeback). Set format=csv for a CSV download." }, "response": [] } ] } ] } ] }