Create an API key

POST /v1/api-keys

Creates an active key of the caller's Organization for one environment and answers ApiKeyCreated, the one answer that shows the full key (1.51.0, FR-identity-2); the api stores a per-key salt, the SHA-256 of salt and secret, and the prefix. A replay under the same Idempotency-Key creates nothing and answers secret null. A scope no API key may exercise is refused with validation_failed and the issue scope_session_only at /scopes/<i>, and an expires_at that is not in the future with expires_at_not_future; a scope the creator's role does not hold is refused with forbidden and the detail scope_not_grantable at /scopes/<i>, and a live key asked by a role that manages test keys only with the detail environment_not_grantable at /environment. From 1.57.0 (workspace ADR 0048 decision 2) a content scope (transcripts:read, tool_payloads:read, model_io:read, recordings:read) whose class the creator's role does not have allowed in the Compliance profile's content_visibility is refused with validation_failed and the issue content_scope_not_allowed at /scopes/<i> (contentScopeIssues), so a Member limited to reveal cannot mint a key that reads without a grant. The Audit event identity.api_key.create records the key id, its environment and its scopes, never the secret. Session only (api.md section 2): the api refuses the route to every API key with forbidden, whatever its scopes; Phase 0 accepts a Member ID token.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the api_keys:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/api-keys" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<name>",
    "environment": "live",
    "scopes": [
      "agents:read"
    ]
  }'

const response = await fetch(`${process.env.VOCAL_API}/v1/api-keys`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<name>",
    "environment": "live",
    "scopes": [
      "agents:read"
    ]
  }),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/api-keys",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "<name>",
        "environment": "live",
        "scopes": [
            "agents:read",
        ],
    },
)
print(response.status_code, response.text)

Parameters

Request body

Content type application/json, required: ApiKeyCreateRequest.

Responses

Fields of the 201 answer

The shape is ApiKeyCreated.