Authentication - KnoxCall Docs

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

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). This is what the SDKs use under the hood, and the recommended path for new integrations.
Long-lived API keys (tk_live_…, tk_test_…, AKE…) — the original path, still works everywhere; treat it as the legacy alternative.

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 clients that are not API keys

A client created on the OAuth Clients page (or via POST /v1/oauth-clients) has no API key behind it. Its client_credentials tokens call /v1 with whatever roles the client holds — assign them when you create the client, or later on its Permissions tab. A client with no role is denied on every /v1 endpoint, and its allowed_scopes narrow each token further; a token can never do more than both its scope and the client’s roles allow. A token issued to a user (authorization-code and device flows, including knoxcall login) calls /v1 as that user: their own roles in the workspace, narrowed by the token’s scope. Whatever roles or custom policies the user holds, a user-bound token:

needs an enrolled second factor to act on the Live host;
never performs a human-plane action — revealing a secret’s plaintext, managing permissions, changing custody. Those need a signed-in session with MFA and step-up, not a bearer token;
never uses a reveal-class permission — decrypting (transit:decrypt), detokenizing a vault value, minting a database credential, issuing a certificate that comes back with its private key (from the PKI engine, or a client’s mTLS certificate with mode: issue — registering a certificate you generated yourself by its sha256_thumbprint still works), or fetching a live upstream OAuth2 token — and never gives one to a machine credential: it cannot attach a role carrying one to a new API key, or rotate the secret of an OAuth client that holds one. Automation that needs these uses an API key or OAuth client that an owner or admin grants the permission in the dashboard;
uses owner and admin capabilities only for an owner or admin of the workspace, as in the dashboard: listing, minting and revoking API keys; creating, changing and deleting OAuth apps; registering agents; changing AI gateways and minting their tokens; managing transit keys and rewrapping or signing with them (on /v1, managing includes listing keys and reading a key’s metadata, which the dashboard shows to any member); managing PKI and database credentials; vaults; webhook test sends; and the ephemeral proxy;
needs an edit permission, not only a read one, to mint or revoke a wrap token or to report egress observations — secret:update for POST / DELETE /v1/wrap/tokens, route:create for POST /v1/wrap/egress-observations. An API key keeps doing these on read alone.

These are the only bounds a user-bound token adds to the user’s roles. A custom role or policy is part of a user’s roles only when it contains a deny rule (or any rule that is not a well-formed allow). One made only of allow rules is no longer held by any person (see the 2026-10-08 entry in the changelog), and a custom role can no longer be assigned to a person. One that contains a deny rule stays on the person who holds it, and on /v1 both its denies and its allows still apply. API keys and OAuth clients are not affected.

OAuth 2.1 endpoints

Endpoint	Purpose	RFC
`POST /oauth/token`	Mint access + refresh tokens	RFC 6749
`POST /oauth/device_authorization`	Start a device-code flow (headless machines)	RFC 8628
`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). Public clients may register loopback redirect URIs per RFC 8252 — http://127.0.0.1, http://[::1], and http://localhost match on any port at authorization time, so native and CLI apps can receive the callback locally.
urn:ietf:params:oauth:grant-type:device_code — RFC 8628 device-code flow for headless/SSH machines: POST /oauth/device_authorization returns a user code, the user approves it at /oauth/activate on any browser, and the device polls the token endpoint. This is what knoxcall login --device uses.
refresh_token — single-use rotation with family-detection theft protection
urn:ietf:params:oauth:grant-type:token-exchange — workload identity federation. Any OIDC issuer works; the SDKs additionally auto-detect several platforms for you (see below)

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)

Running on a platform that issues its workloads an OIDC token? You don’t need an API key at all. Register a binding, and the exchange trades that token for a short-lived KnoxCall access token. Any OIDC issuer is accepted — if it publishes /.well-known/openid-configuration over https and signs with any asymmetric algorithm (the full RS/PS/ES family plus EdDSA — see What your issuer’s token must carry below), you can federate from it by registering the issuer and the claims that identify your workload. Auto-detection is a convenience on top of that. Where the SDK recognises the platform it fetches the token for you with no configuration: GitHub Actions, Google Cloud, AWS (IRSA), Azure managed identity, Vercel, CircleCI and Buildkite. Coverage differs by language — the Node SDK covers all seven, the Python SDK covers five (no Azure, no Buildkite). On any other platform, or from an SDK that does not detect yours, fetch the token yourself and call the exchange directly; HCP Terraform works this way today.

Which claims identify your workload depends on the issuer. KnoxCall carries a claim table for three issuers — GitHub Actions (repository, job_workflow_ref or sub), HCP Terraform (sub) and Google (email or sub) — and requires your binding to pin at least one of them. Every other issuer falls back to sub alone, which works but is a blunter instrument: sub is the only claim OIDC guarantees identifies a subject. This matters because a binding that pins no identifying claim would describe a population rather than a workload — on a shared issuer like GitHub’s, {"ref": "refs/heads/main"} is true for every repository on GitHub — so the API refuses one with 400.

# GitHub Actions example — zero stored secrets
- run: |
    npm install @knoxcall/sdk@^1.0.0
    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.

What your issuer’s token must carry

These are checked on every exchange, on both POST /oauth/token and POST /v1/oauth/token. Every mainstream IdP satisfies them by default; they are listed because a refusal that names a missing claim is easier to fix than one that does not.

Requirement	Why
A `kid` in the JWS header	It names which of the issuer’s published keys signed the token. Required even when the issuer publishes only one key — otherwise the rule would switch itself off for the length of a key rotation, which is precisely when key selection needs to be unambiguous.
An `exp` claim	It is the only claim that bounds how long a captured assertion stays usable. A token with no `exp` is refused rather than treated as never expiring.
An `iss` matching a registered binding	The issuer URL is compared to your binding exactly, as a string.
An asymmetric `alg`	One of `RS256/384/512`, `PS256/384/512`, `ES256/384/512`, `EdDSA`. HMAC algorithms (`HS`) and `none` are always refused — the only key material we hold for your issuer is its public* JWKS, so accepting an HMAC would mean verifying a token signed with the key we ourselves published.

Assertions are single use. Each one is spent by the exchange that accepts it, so a long-running job must mint a fresh token from its platform before each exchange rather than reusing the first — the SDKs’ WorkloadCredentialProvider does this for you.

Create an OAuth client

An OAuth client is how an SDK or a script authenticates in CI and on servers. (On a developer machine you can log in once with the CLI instead.) You create it once in the dashboard:

Switch the dashboard to the mode you want to call, Live or Test. A client belongs to the mode it was created in.
Open Settings → API → OAuth Clients and click Create OAuth Client.
Enter a Name (for example my-laptop) and keep the type Server-to-server.
Under Allowed scopes, list the scopes the client needs, separated by spaces. For example, routes:read routes:invoke lets it list your routes and call them through the proxy; add routes:write or secrets:write if it will create them. An empty list is refused.
Under Permissions, keep Key — Read-only (selected by default), or choose Key — Editor if the client will create or change routes, secrets or clients. A client with no role is refused on every /v1 endpoint.
Click Create Client, then copy the Client ID and Client secret. The secret is shown once.

Put the pair in the environment. Every SDK reads it with no code change:

export KNOXCALL_CLIENT_ID="tk_xxxxxxxx"   # the Client ID
export KNOXCALL_CLIENT_SECRET="..."       # the Client secret

A client created in Test mode calls the Test environment, so also pass the SDK’s sandbox option (sandbox: true in Node and Ruby, sandbox=True in Python, Sandbox: true in Go, 'sandbox' => true in PHP).

Using the SDK (recommended)

KnoxCall ships first-party SDKs for Node.js/TypeScript, Python, Go, PHP, and Ruby (plus a Terraform provider and browser/React Elements) — see the SDKs overview for the full family. Every SDK handles token minting, caching, retries, idempotency keys, and DPoP for you.

npm install @knoxcall/sdk@^1.0.0

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

const client = new KnoxCall({ tenant: "acme" });
const routes = await client.routes.list();

from knoxcall import KnoxCall

# Credentials from KNOXCALL_CLIENT_ID / KNOXCALL_CLIENT_SECRET
client = KnoxCall()
page = client.routes.list()
routes = page["data"]

client, err := knoxcall.New(knoxcall.Options{})
if err != nil {
    log.Fatal(err)
}
page, err := client.Routes.List(context.Background(), nil)
// page.Data holds the routes

$client = new KnoxCall(); // env-configured
$page   = $client->routes->list();
$routes = $page['data'];

client = KnoxCall::Client.new # env-configured
page   = client.routes.list
routes = page["data"]

# Mint a 1-hour OAuth token (client_credentials) — see Quick start above
TOKEN=$(curl -s -X POST https://api.knoxcall.com/oauth/token \
  -u "$KNOXCALL_CLIENT_ID:$KNOXCALL_CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq -r .access_token)

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

Every SDK handles credential auto-detection, token caching, refresh, retries, and DPoP signing — your code just calls methods. Prefer raw REST? Mint a short-lived OAuth token and pass it as Authorization: Bearer <token> (a legacy tk_… key in the same header also works) and parse the JSON response.

Log in once with the CLI

On a developer machine, skip keys and env vars entirely. Every KnoxCall SDK package ships the knoxcall command (pip, npm, gem, Composer, go install — same surface, same credentials file); it runs the authorization-code + PKCE flow in your browser (or the RFC 8628 device-code flow with --device) and stores the credential in ~/.knoxcall/credentials.json:

pip install "knoxcall>=1.0,<2.0"  # or your ecosystem's equivalent — every SDK ships the CLI
knoxcall login                    # opens your browser (PKCE); prints the URL too
knoxcall login --device           # headless/SSH machines: device-code flow
knoxcall whoami                   # show the signed-in tenant
knoxcall logout                   # revoke + remove the stored credential

Your browser opens the KnoxCall dashboard. Sign in if you are not already, check what is being authorized, choose the workspace and click Approve — the terminal finishes on its own. With --device, open the link the terminal prints on any device, confirm the code it shows, and approve there. Approving needs an account with a passkey, security key or authenticator app set up. knoxcall login signs you in to Live. To call the Test environment, use an OAuth client created in Test mode and the SDK’s sandbox option. Every KnoxCall SDK — Node.js, Python, Go, PHP, and Ruby — picks the file up automatically, so a zero-argument constructor just works:

from knoxcall import KnoxCall

client = KnoxCall()  # tenant and base URL come from the login

Access tokens refresh themselves; refreshes are cross-process safe (file lock + atomic rotation of the single-use refresh token). Behind the scenes, knoxcall login uses the reserved knoxcall-cli client alias, which provisions a per-tenant system OAuth client on first login — you’ll see it on the OAuth Clients page, where it is visible but protected. See the SDKs overview for profiles (KNOXCALL_PROFILE) and the full credential-resolution order.

Postman / Insomnia / Bruno

KnoxCall Postman collection

Download the official collection and import it into Postman. 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	A live key. On the management API it can do only what its attached roles allow — with no role it is refused on every policy-gated `/v1` endpoint, and can reach only the API root and the two endpoints that describe the key itself (`GET /v1/account`, `GET /v1/account/usage`). Available on all plans.
Enterprise Access	`AKE`	Production	A live access-key pair (access key ID + secret access key). Enterprise plan only. It is created with no roles and the default 90-day expiry; neither scopes nor expiry are chosen when you create it.
Test	`tk_test_`	Sandbox	A sandbox key, authorized by its roles exactly like a standard key. 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.

A key’s roles do not limit which of your routes it can call. Roles are enforced on the /v1 management API only; the proxy does not evaluate them, so any active key can call any enabled route in its mode, whatever roles it holds. Contain proxied use with each route’s Require authorized clients setting and IP allowlist — see Creating API keys.

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:

# $TOKEN is a minted OAuth access token — see the Quick start above
curl -X POST https://api.knoxcall.com/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -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": "550e8400-e29b-41d4-a716-446655440000"
  }
}

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.

import "github.com/knoxcall/sdk-go/knoxcall"

client, err := knoxcall.New(knoxcall.Options{
    Tenant:  "acme",
    Sandbox: true, // → https://sandbox.knoxcall.com + https://sandbox-acme.knoxcall.com
    APIKey:  "tk_test_...",
})

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.

Making Authenticated REST Requests

The SDK is the recommended path — it mints, caches, and refreshes tokens for you. Calling the REST API directly, mint a short-lived OAuth token (see Quick start) and pass it in the Authorization header as a Bearer token:

Examples

# Mint a 1-hour OAuth token (client_credentials)
TOKEN=$(curl -s -X POST https://api.knoxcall.com/oauth/token \
  -u "$KNOXCALL_CLIENT_ID:$KNOXCALL_CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq -r .access_token)

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

import os
import requests

headers = {
    # OAuth access token minted via POST /oauth/token
    "Authorization": f"Bearer {os.environ['KNOXCALL_ACCESS_TOKEN']}"
}

# List all routes
response = requests.get(
    "https://api.knoxcall.com/v1/routes",
    headers=headers
)

routes = response.json()["data"]
for route in routes:
    print(f"{route['name']} - {route['target_base_url']}")

// OAuth access token minted via POST /oauth/token
const TOKEN = process.env.KNOXCALL_ACCESS_TOKEN;

const response = await fetch("https://api.knoxcall.com/v1/routes", {
  headers: {
    Authorization: `Bearer ${TOKEN}`
  }
});

const { data: routes } = await response.json();
routes.forEach(route => {
  console.log(`${route.name} - ${route.target_base_url}`);
});

<?php

// OAuth access token minted via POST /oauth/token
$token = getenv('KNOXCALL_ACCESS_TOKEN');

$ch = curl_init('https://api.knoxcall.com/v1/routes');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$token}"
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
foreach ($data['data'] as $route) {
    echo "{$route['name']} - {$route['target_base_url']}\n";
}

Legacy: Long-Lived API Keys

Long-lived keys (tk_live_…, tk_test_…, AKE…) remain fully supported on the Management API. Pass the key exactly where the token goes:

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

Legacy: Using the x-api-key Header

If your HTTP client or framework makes it difficult to set the Authorization header, you can pass a long-lived API key in the x-api-key header instead:

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

import requests

response = requests.get(
    "https://api.knoxcall.com/v1/routes",
    headers={"x-api-key": "tk_live_abc123..."}
)

const response = await fetch("https://api.knoxcall.com/v1/routes", {
  headers: { "x-api-key": process.env.KNOXCALL_API_KEY }
});

<?php

$ch = curl_init('https://api.knoxcall.com/v1/routes');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "x-api-key: " . getenv('KNOXCALL_API_KEY')
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

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": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Security Best Practices

Never expose keys in client-side code

An API key can call your routes with your credentials injected, and do whatever its roles allow on the management API. Never embed one 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

Attach the narrowest role each key needs — roles limit what it can do on the management API — and create a separate key per service so you can revoke one without the others. Roles do not limit which routes a key can call: require authorized clients or an IP allowlist on each route.

Environment Variable Setup

On a developer machine, prefer knoxcall login — no environment variables at all. For CI and servers, create an OAuth client (dashboard → Settings → API → OAuth Clients) and set KNOXCALL_CLIENT_ID + KNOXCALL_CLIENT_SECRET — every SDK picks them up automatically. KNOXCALL_API_KEY remains supported as the legacy spelling for a long-lived key.

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

# Or use a .env file with dotenv
echo 'KNOXCALL_CLIENT_ID=...' >> .env
echo 'KNOXCALL_CLIENT_SECRET=...' >> .env

# Legacy long-lived key (still supported)
export KNOXCALL_API_KEY="tk_live_abc123..."

# Set for current session
$env:KNOXCALL_CLIENT_ID = "..."
$env:KNOXCALL_CLIENT_SECRET = "..."

# Set permanently for current user
[System.Environment]::SetEnvironmentVariable("KNOXCALL_CLIENT_ID", "...", "User")
[System.Environment]::SetEnvironmentVariable("KNOXCALL_CLIENT_SECRET", "...", "User")

services:
  app:
    environment:
      - KNOXCALL_CLIENT_ID=...
      - KNOXCALL_CLIENT_SECRET=...
    # Or reference a .env file
    env_file:
      - .env

# Prefer workload identity federation — zero stored secrets (see
# "Workload identity federation" above). Otherwise store the client
# secret as a repository secret and reference it:
env:
  KNOXCALL_CLIENT_ID: ${{ secrets.KNOXCALL_CLIENT_ID }}
  KNOXCALL_CLIENT_SECRET: ${{ secrets.KNOXCALL_CLIENT_SECRET }}

Never add .env files containing credentials 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 clients that are not API keys

​OAuth 2.1 endpoints

​DPoP — sender-constrained tokens (RFC 9449)

​Workload identity federation (RFC 8693)

​What your issuer’s token must carry

​Create an OAuth client

​Using the SDK (recommended)

​Log in once with the CLI

​Postman / Insomnia / Bruno

KnoxCall Postman collection

​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

​Making Authenticated REST Requests

​Examples

​Legacy: Long-Lived API Keys

​Legacy: 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 clients that are not API keys

OAuth 2.1 endpoints

DPoP — sender-constrained tokens (RFC 9449)

Workload identity federation (RFC 8693)

What your issuer’s token must carry

Create an OAuth client

Using the SDK (recommended)

Log in once 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

Making Authenticated REST Requests

Examples

Legacy: Long-Lived API Keys

Legacy: Using the x-api-key Header

Authentication Errors

Security Best Practices

Environment Variable Setup

Key Rotation Procedure