Skip to main content

​
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 TypePrefixEnvironmentDescription
Standardtk_live_ProductionFull access to production resources. Available on all plans.
Enterprise AccessAKEProductionEnhanced keys with configurable scopes and expiration. Enterprise plan only.
Testtk_test_SandboxFull 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

  1. Log in to the KnoxCall Dashboard.
  2. Navigate to Settings in the sidebar.
  3. Scroll to the API Keys section.
  4. Click Create API Key.
  5. Give your key a descriptive name (e.g., “CI/CD Pipeline”, “Backend Server”).
  6. 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": {
    "id": "ak_3f8a9b2c",
    "name": "Deployment Key",
    "key": "tk_live_newkey789...",
    "created_at": "2026-02-20T14:30:00Z"
  },
  "meta": {
    "request_id": "req_..."
  }
}
The 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.

Production

Base URL: https://api.knoxcall.com/v1
  • 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

Base URL: https://sandbox.knoxcall.com/v1
  • 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.

​
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 TypeStatusCauseSolution
authentication_required401No API key providedAdd the Authorization or x-api-key header to your request
invalid_api_key401Key is invalid, revoked, or expiredCheck that the key is correct and has not been revoked in the dashboard
wrong_key_type403Test key used on production, or live key used on sandboxMatch the key type to the correct base URL
subscription_inactive403Tenant subscription is paused or cancelledUpdate 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

  1. Create a new API key in the dashboard or via the API.
  2. Update your application’s environment variables with the new key.
  3. Deploy the updated configuration.
  4. Verify that requests succeed with the new key.
  5. 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.