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. 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. 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.

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
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

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