Create API Key

POST /v1/api-keys

Creates a new API key. The full key value is returned only once in the response — store it securely.

For new integrations we recommend OAuth clients or the SDK instead of long-lived API keys — short-lived tokens, scope narrowing, and no long-lived secret to store. See the Authentication guide. This endpoint remains fully supported; the examples below authenticate with a minted OAuth access token ($TOKEN).

Request Body

Field	Type	Required	Description
`name`	string	Yes	A descriptive name (e.g., “CI/CD Pipeline”, “Backend Server”)
`rate_limit_requests`	integer	No	Maximum requests per window for this key
`rate_limit_window_sec`	integer	No	Rate limit window duration in seconds
`role_ids`	array of uuid	No	Permission roles to attach, assigned in the same transaction as the key. Max 20. Only the seeded key roles (`Key — Invoke`, `Key — Read-only`, `Key — Editor`, `Key — Infrastructure`) are accepted: custom roles are being retired in favour of per-key permissions. See List Roles.

The key_type is set automatically based on the host the request is sent to and cannot be specified in the request body. Requests to api.knoxcall.com produce a standard key; requests to sandbox.knoxcall.com produce a test key.

Response

{
  "data": {
    "key_id": "tk_9f3a1c2e",
    "api_key": "tk_9f3a1c2e_4d2b8a1f0c9e7d6b5a4c3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e1",
    "key_prefix": "tk_9f3a1c2e_",
    "key_type": "standard",
    "name": "CI/CD Pipeline",
    "id": "f0a1b2c3-d4e5-6f7a-8b9c-0d1e2f3a4b5c",
    "role_ids": [],
    "message": "Store this API key securely. It will not be shown again."
  },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}

The api_key field contains the full key and is only returned at creation time. KnoxCall does not store the plain-text key. If you lose it, you must revoke it and create a new one.

# $TOKEN is a minted OAuth access token — see /api-reference/authentication
curl -X POST https://api.knoxcall.com/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline"
  }'

import os
import requests

resp = requests.post(
    "https://api.knoxcall.com/v1/api-keys",
    headers={
        "Authorization": f"Bearer {os.environ['KNOXCALL_ACCESS_TOKEN']}",
        "Content-Type": "application/json"
    },
    json={"name": "CI/CD Pipeline"}
)
new_key = resp.json()["data"]
print(f"Store this key: {new_key['api_key']}")

const resp = await fetch("https://api.knoxcall.com/v1/api-keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KNOXCALL_ACCESS_TOKEN}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "CI/CD Pipeline" })
});
const { data: newKey } = await resp.json();
console.log(`Store this key: ${newKey.api_key}`);

Permissions on the new key

A key created with no role_ids holds no policy, and is therefore default-denied on every policy-gated endpoint — it authenticates, then 403s. That is the platform default since the legacy *:* auto-attach was retired, and it is almost never what you want.

Roles govern the /v1 management API, not calls to your routes. The proxy does not evaluate a key’s roles today: any active key can call any enabled route in its mode (Live or Test) — including a key holding only Key — Read-only, or no role at all. What limits proxied calls is each route’s own configuration: Require authorized clients (set per environment — the caller must be one of the route’s clients, identified by source IP or mTLS certificate) and the route’s IP allowlist. An OAuth access token minted with explicit scopes is narrowed on the proxy as well: it needs routes:invoke:<slug> for one route, or routes:invoke, routes:* or *:* for every route. Management scopes such as routes:read and routes:write do not let it call a route.

List the roles you can attach with GET /v1/roles?subject_kind=api_key and pass their ids:

curl -X POST https://api.knoxcall.com/v1/api-keys   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{ "name": "terraform-prod", "role_ids": ["b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"] }'

A key can never mint a key more privileged than itself. Every rule in every requested role must be covered by a rule the calling credential already holds. If it is not, the request is refused with 403 privilege_escalation and the response names the offending grant verbatim so you can see exactly what was rejected:

{
  "error": {
    "type": "privilege_escalation",
    "message": "This API key cannot grant a permission it does not itself hold. Refused grant from role \"Key — Infrastructure\": {\"resource_type\":\"vault\",\"actions\":[\"create\"],\"effect\":\"allow\"} — no rule in your own policy set grants it.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Two grants can never be delegated at all by a key holding only a wildcard (*:*) rule: secret:reveal and the custody / workload-binding actions. Delegating one requires the calling key to name that exact (resource_type, action) pair literally.

A scope-narrowed OAuth access token cannot create API keys, with or without role_ids. An API key carries no scope narrowing, so any key such a token created would exceed the token’s own grant; the call returns 403 privilege_escalation. Create keys with an API key, or with an OAuth token whose scope is not narrowed (no scope requested, or *).

Errors

Status	Type	Description
400	`validation_error`	Missing `name` field; `role_ids` is not an array of UUIDs; more than 20 role ids; or a requested role’s audience is `user`, not `api_key`
403	`privilege_escalation`	A requested role grants a permission the calling key does not itself hold (the message names the offending grant verbatim), or the call was made with a scope-narrowed OAuth token, which cannot create an API key at all
403	`forbidden`	A requested role is not one of the seeded key roles. Custom roles are being retired: a key that already holds one keeps it, but no new key can be given one
404	`not_found`	A `role_ids` entry does not exist in your tenant (another tenant’s role id is indistinguishable from a nonexistent one, by design)

Overview

Workload Identity

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Changelog

Create API Key

Create API Key

Request Body

Response

Permissions on the new key

Errors

​Create API Key

​Request Body

​Response

​Permissions on the new key

​Errors

Create API Key

Request Body

Response

Permissions on the new key

Errors