Account

API Keys

API keys are the credentials your applications and agents present at the LLM Proxy and MCP Firewall data plane. They are distinct from the Personal Access Token used for this management API.

Concepts#

Two kinds of credentials

Personal Access Token (PAT) — authenticates you against the management API documented in this site. One per user.

API key — what your runtime workloads send to the AIronClaw data-plane proxies. Many per user, each tagged with the LLM/MCP resources it can touch.

API keys carry permission tags that scope what they can access:

name:<label> — the human-readable name (set once at creation, unchangeable on update).
llm:<proxyId>:read, llm:<proxyId>:write, optionally with :model:<name> for a model-level allow-list.
mcp:<proxyId>:tool:* or mcp:<proxyId>:tool:<toolName> for tool allow-lists; same shape for resource:.

Tags are constructed server-side from the structured input — you cannot pass a raw tags: [...] array. Every UUID in the input is cross-checked against your owned proxies, so you cannot grant a key permissions on resources owned by another user.

List keys#

GET/api/keys

Returns every API key owned by the caller, with the plaintext masked (aifw_p…_xyz4). The plaintext is unrecoverable after creation.

curl https://app.aironclaw.com/api/keys \
  -H "Authorization: Bearer $AIFW_PAT"

Create a key#

POST/api/keys

Creates a new key, returns the plaintext exactly once, and enforces the per-user key quota (returns 403 when exhausted).

Body

name*

string

Human-readable label. Pinned for the lifetime of the key.

mcpPermissions

object[]

Array of { id, tools?: string[], resources?: string[] }. Omit tools / resources for full access; pass [\"*\"] for the same effect explicitly.

llmPermissions

object[]

Array of { id, models?: string[] }. Omit models for full access.

customTags

string[]

Free-form labels for your own bookkeeping (e.g. env:prod). Cannot collide with reserved namespaces (name:, llm:, mcp:).

curl -X POST https://app.aironclaw.com/api/keys \
  -H "Authorization: Bearer $AIFW_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "terraform",
    "llmPermissions": [
      { "id": "8b3f9c5a-...-d21", "models": ["gpt-4o-mini"] }
    ],
    "mcpPermissions": [
      { "id": "f4a2-...-b81", "tools": ["read_file", "list_dir"] }
    ],
    "customTags": ["env:prod"]
  }'

Update a key#

PATCH/api/keys/:id

Replaces the key's permission tags with a freshly built set from the same body shape as create (minus name, which is immutable). The plaintext key and its id are unchanged.

curl -X PATCH https://app.aironclaw.com/api/keys/$KEY_ID \
  -H "Authorization: Bearer $AIFW_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "llmPermissions": [{ "id": "8b3f...d21" }],
    "mcpPermissions": []
  }'

Delete a key#

DELETE/api/keys/:id

Revokes the key immediately. In-flight requests may complete; new requests using this key will return 401.

curl -X DELETE https://app.aironclaw.com/api/keys/$KEY_ID \
  -H "Authorization: Bearer $AIFW_PAT"