Authentication - KnoxCall Docs

KnoxCall supports two authentication paths, both fully supported, both safe to mix:

Long-lived API keys (tk_live_…, tk_test_…, AKE…) — the original path, still works everywhere.
OAuth 2.1 short-lived access tokens (kc_live_…, kc_test_…) — minted via POST /oauth/token, expire in 1 hour, optionally sender-constrained with DPoP (RFC 9449).

If you’ve used Auth0, Okta, AWS Cognito, Stripe Connect, or any modern OAuth provider, our OAuth surface will feel identical — every endpoint conforms to a published IETF RFC.

Quick start — OAuth 2.1

# Mint a 1-hour token from your existing API key
TOKEN=$(curl -s -X POST https://api.knoxcall.com/oauth/token \
  -u "tk_abcd1234:rest_of_key" \
  -d "grant_type=client_credentials" \
  | jq -r .access_token)

# Use it like any Bearer token
curl -H "Authorization: Bearer $TOKEN" https://api.knoxcall.com/v1/routes

Your existing tk_… API key becomes the OAuth client_id + client_secret:

client_id = tk_abcd1234 (everything before the second underscore)
client_secret = the remainder

The OAuth path adds:

1-hour TTL instead of long-lived
Scope narrowing — request a subset of your key’s permissions per call
DPoP sender-constraint (optional) — proof-of-possession of a keypair required per request

OAuth 2.1 endpoints

Endpoint	Purpose	RFC
`POST /oauth/token`	Mint access + refresh tokens	RFC 6749
`POST /oauth/introspect`	Validate a token (relying-party use)	RFC 7662
`POST /oauth/revoke`	Revoke a token	RFC 7009
`GET /.well-known/oauth-authorization-server`	Discovery	RFC 8414

Supported grant types:

client_credentials — server-to-server, the simplest path
authorization_code + PKCE — human consent flow (with refresh tokens)
refresh_token — single-use rotation with family-detection theft protection
urn:ietf:params:oauth:grant-type:token-exchange — workload identity federation (GitHub Actions, GCP, AWS, Azure, Vercel)

DPoP — sender-constrained tokens (RFC 9449)

For tenants requiring the highest security tier, request DPoP-bound tokens. Send a DPoP proof JWT on the token request; the issued token is bound to your keypair via the cnf.jkt claim. Every subsequent API call must carry a fresh DPoP proof signed by the same key.

// Use the SDK — DPoP is transparent
import { KnoxCall } from "@knoxcall/sdk";
const client = new KnoxCall({ tenant: "acme", dpop: "always" });

Workload identity federation (RFC 8693)

Run on GitHub Actions, GCP, AWS, Azure, or Vercel? You don’t need an API key at all. The SDK detects your platform and exchanges its OIDC token for a KnoxCall access token automatically.

# GitHub Actions example — zero stored secrets
- run: |
    npm install @knoxcall/sdk
    node my-script.js
  env:
    KNOXCALL_TENANT: acme
permissions:
  id-token: write

Configure the trust binding once in the KnoxCall dashboard under Settings → Workload Identity. Subsequent CI runs auto-authenticate.

Using the SDK (recommended)

KnoxCall publishes a first-party SDK for Node.js / TypeScript. For other languages, use the REST API directly with your preferred HTTP client.

npm install @knoxcall/sdk

The Node.js SDK handles auto-detection, token caching, refresh, retries, and DPoP signing — your code just calls methods. For all other languages, pass your API key as Authorization: Bearer <key> and parse the JSON response.

Using curl with the CLI

brew install knoxcall
knoxcall login                                          # one-time
curl $(knoxcall auth) https://api.knoxcall.com/v1/routes

The CLI silently refreshes when the cached token is stale.

Postman / Insomnia / Bruno

Import the official KnoxCall Postman collection. It uses Postman’s native OAuth 2.0 support — sign in once via the Authorization tab, and every saved request inherits the token. For other tools, point them at the OAuth 2.0 discovery URL: https://api.knoxcall.com/.well-known/oauth-authorization-server.

API Key Types

KnoxCall uses API keys to authenticate requests to the Management API. There are three types of keys, each with a distinct prefix:

Key Type	Prefix	Environment	Description
Standard	`tk_live_`	Production	Full access to production resources. Available on all plans.
Enterprise Access	`AKE`	Production	Enhanced keys with configurable scopes and expiration. Enterprise plan only.
Test	`tk_test_`	Sandbox	Full access to sandbox resources. Safe for development and testing.

Key prefixes make it easy to identify which environment a key belongs to at a glance. This follows the same live/test paradigm used by Stripe and other modern APIs.

Creating API Keys

Via the Dashboard

Log in to the KnoxCall Dashboard.
Navigate to Settings in the sidebar.
Scroll to the API Keys section.
Click Create API Key.
Give your key a descriptive name (e.g., “CI/CD Pipeline”, “Backend Server”).
Copy the key immediately — it will only be shown once.

API keys are displayed only once at creation time. If you lose a key, you must revoke it and create a new one. KnoxCall never stores keys in plain text after initial creation.

Via the API

You can also create API keys programmatically:

curl -X POST https://api.knoxcall.com/v1/api-keys \
  -H "Authorization: Bearer tk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deployment Key"
  }'

Response:

{
  "data": {
    "key_id": "ak_3f8a9b2c",
    "api_key": "tk_live_newkey789...",
    "key_prefix": "tk_live_newk",
    "key_type": "standard",
    "name": "Deployment Key",
    "message": "Store this API key securely. It will not be shown again."
  },
  "meta": {
    "request_id": "req_..."
  }
}

The api_key field in the response is the only time the full API key is returned. Store it securely.

Production vs. Sandbox

KnoxCall provides completely separate production and sandbox environments, following the same live/test key paradigm popularized by Stripe. Routes, secrets, environments, webhooks, vaults, crypto keys, PKI authorities, OAuth clients, and workflows are all isolated between the two modes — nothing leaks across.

Production (Live)

Management API: https://api.knoxcall.com/v1Proxy traffic: https://{slug}.knoxcall.com/{route}

Uses tk_live_ or AKE prefixed keys
Routes proxy real traffic to live upstream APIs
Secrets contain real credentials
Usage counts against your plan limits
Changes affect your live integrations immediately

Sandbox (Test)

Management API: https://sandbox.knoxcall.com/v1Proxy traffic: https://sandbox-{slug}.knoxcall.com/{route}

Uses tk_test_ prefixed keys
Routes, secrets, and clients are isolated from production
Safe for development, testing, and CI/CD
No impact on production traffic or billing
Mirrors production API behavior exactly

Using a test key against the production API (or vice versa) will return a 403 error with the type wrong_key_type. Make sure your environment configuration matches the correct base URL and key type.

Dashboard toggle

The admin dashboard has a Live / Test toggle in the bottom-left of the sidebar (look for the flask icon). Click it to switch the entire dashboard between modes — every page (Routes, Secrets, Vaults, API Keys, Webhooks, etc.) refetches and shows only the data for the active mode. An amber banner across the top of the screen confirms when you are in Test mode. While in Test mode:

Creating an API key automatically produces a tk_test_ test key (the standard / Enterprise Access Key options are hidden).
Creating any other resource (route, secret, vault, etc.) stamps it as sandbox — it is invisible from Live mode.
Existing live resources are not visible; you start with an empty sandbox until you populate it.

Switching back to Live mode restores the production view immediately. Your selection persists across browser sessions.

Using the SDK in sandbox mode

Both the Node and Go SDKs accept a sandbox: true option which auto-resolves the management and proxy base URLs to the sandbox hostnames:

import { KnoxCall } from "@knoxcall/sdk";

const client = new KnoxCall({
  tenant: "acme",
  sandbox: true, // → https://sandbox.knoxcall.com + https://sandbox-acme.knoxcall.com
});

// Use a tk_test_ key — required for sandbox.

Equivalent environment variables work everywhere (CI, Docker, etc.): set KNOXCALL_BASE_URL=https://sandbox.knoxcall.com and KNOXCALL_PROXY_BASE_URL=https://sandbox-{slug}.knoxcall.com.

Audit logs

Every audit log entry is stamped with details.sandbox: true|false so you can filter live vs test activity in the Audit Logs page or via the /v1/audit-logs endpoint. Background jobs (cron, queue workers) always emit sandbox: false.

Using API Keys

Pass your API key in the Authorization header as a Bearer token, or use the x-api-key header.

Examples

curl https://api.knoxcall.com/v1/routes \
  -H "Authorization: Bearer tk_live_abc123..."

Using the x-api-key Header

If your HTTP client or framework makes it difficult to set the Authorization header, you can use the x-api-key header instead:

curl https://api.knoxcall.com/v1/routes \
  -H "x-api-key: tk_live_abc123..."

Authentication Errors

When authentication fails, the API returns one of these error types:

Error Type	Status	Cause	Solution
`authentication_required`	401	No API key provided	Add the `Authorization` or `x-api-key` header to your request
`invalid_api_key`	401	Key is invalid, revoked, or expired	Check that the key is correct and has not been revoked in the dashboard
`wrong_key_type`	403	Test key used on production, or live key used on sandbox	Match the key type to the correct base URL
`subscription_inactive`	403	Tenant subscription is paused or cancelled	Update your billing information in the dashboard

Example error response:

{
  "error": {
    "type": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "request_id": "req_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Security Best Practices

Never expose keys in client-side code

API keys grant full access to your KnoxCall configuration. Never embed them in frontend JavaScript, mobile apps, or any code that runs in the browser.

Use environment variables

Store API keys in environment variables or a secrets manager. Never hard-code them in source files or commit them to version control.

Rotate keys regularly

Create new keys and revoke old ones on a regular cadence. If a key is compromised, revoke it immediately from the dashboard.

Use the principle of least privilege

On Enterprise plans, use scoped access keys (AKE) to limit what each key can do. For standard plans, create separate keys per service so you can revoke individually.

Environment Variable Setup

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export KNOXCALL_API_KEY="tk_live_abc123..."

# Or use a .env file with dotenv
echo 'KNOXCALL_API_KEY=tk_live_abc123...' >> .env

Never add .env files containing API keys to version control. Add .env to your .gitignore file.

Key Rotation Procedure

Create a new API key in the dashboard or via the API.
Update your application’s environment variables with the new key.
Deploy the updated configuration.
Verify that requests succeed with the new key.
Revoke the old key in the dashboard.

Both the old and new keys will work simultaneously until you revoke the old one. This allows zero-downtime rotation.

​Quick start — OAuth 2.1

​OAuth 2.1 endpoints

​DPoP — sender-constrained tokens (RFC 9449)

​Workload identity federation (RFC 8693)

​Using the SDK (recommended)

​Using curl with the CLI

​Postman / Insomnia / Bruno

​API Key Types

​Creating API Keys

​Via the Dashboard

​Via the API

​Production vs. Sandbox

Production (Live)

Sandbox (Test)

​Dashboard toggle

​Using the SDK in sandbox mode

​Audit logs

​Using API Keys

​Examples

​Using the x-api-key Header

​Authentication Errors

​Security Best Practices

Never expose keys in client-side code

Use environment variables

Rotate keys regularly

Use the principle of least privilege

​Environment Variable Setup

​Key Rotation Procedure

Quick start — OAuth 2.1

OAuth 2.1 endpoints

DPoP — sender-constrained tokens (RFC 9449)

Workload identity federation (RFC 8693)

Using the SDK (recommended)

Using curl with the CLI

Postman / Insomnia / Bruno

API Key Types

Creating API Keys

Via the Dashboard

Via the API

Production vs. Sandbox

Dashboard toggle

Using the SDK in sandbox mode

Audit logs

Using API Keys

Examples

Using the x-api-key Header

Authentication Errors

Security Best Practices

Environment Variable Setup

Key Rotation Procedure