API keys

API keys authenticate every request to the Inkbox API. Pass the key in the X-API-Key header. Each key has a fixed scope chosen at creation time. The plaintext value is returned only once when the key is created — store it securely; it cannot be retrieved again.

Scopes

Every API key has one of two scopes. Scope is fixed at creation and cannot be changed later.

Admin-scoped

Org-wide authority. An admin-scoped key can act on any resource in the organization and manage org-level configuration — including custom email domains, 10DLC compliance, contact rules, and note access grants.

Agent-scoped

Bound to a single agent identity. The key can only operate as — or on resources owned by — that one agent. Agent-scoped keys are typically issued during the agent signup flow.

What each scope can do

Capability	Admin-scoped	Agent-scoped
Send and receive mail, texts, and calls	✓	✓ (as the bound identity)
Read contacts	✓	✓ (permitted identifiers, profile fields, and memories)
Read notes	✓ (all org resources)	✓ (only what the identity is granted access to)
Manage custom email domains	✓	—
Manage 10DLC compliance	✓	—
Read usage and manage billing settings	✓	—
Manage mail and phone contact rules	✓	—
Grant access to notes	✓	—
Mint new agent-scoped API keys	✓	—
Mint new admin-scoped API keys	—	—

Endpoints that require an admin-scoped key return 403 when called with an agent-scoped key.

Minting rules

Who can mint which kind of key:

Caller	Can mint admin-scoped	Can mint agent-scoped
Console session	✓	✓
Admin-scoped API key	—	✓
Agent-scoped API key	—	—

When minting from an admin-scoped API key, pass scoped_identity_id in the request body to bind the new key to a specific agent identity. Scope is fixed at creation. To rotate a key, mint a new one and revoke the old one. Agent-scoped keys can also be obtained programmatically via the agent signup flow, which mints a key bound to the newly-claimed identity.

Create an agent-scoped key

POST /api/v1/api-keys

Authenticate with an admin-scoped API key and use the target identity’s UUID as scoped_identity_id. You can retrieve the UUID from the identity API.

Field	Type	Required	Description
`label`	string	Yes	Key name, 1–255 characters
`description`	string \| null	No	Description, up to 1,000 characters
`scoped_identity_id`	UUID	Yes for API-key callers	Identity in your organization that the new key can act as

cURL

curl -X POST "https://inkbox.ai/api/v1/api-keys" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Support agent runtime",
    "description": "Key for the support agent",
    "scoped_identity_id": "123e4567-e89b-42d3-a456-426614174000"
  }'

Response (201)

Field	Type	Description
`api_key`	string	Full API key, returned only on creation. Store this value securely
`record`	object	Key metadata, including `id`, `label`, `description`, `scoped_identity_id`, `status`, and timestamps

An agent-scoped caller receives 403. An admin-scoped caller that omits scoped_identity_id also receives 403. An identity outside your organization or an unknown UUID returns 404. To create an admin-scoped key, use the Inkbox Console.

Inspect a key

GET /api-keys/self

Returns metadata for the calling key. The plaintext value is never returned again after creation.

Response (200)

JSON

{
  "id": "ApiKey_8f3a2c91...",
  "scoped_identity_id": null,
  "status": "active",
  "display_prefix": "ApiKey_8f3a2c91-...",
  "last4": "k9X2",
  "created_at": "2026-04-01T10:14:22Z",
  "last_used_at": "2026-05-08T17:02:11Z",
  "expires_at": null,
  "revoked_at": null
}

scoped_identity_id is null for admin-scoped keys, or an identity ID for agent-scoped keys.

Code examples

curl "https://inkbox.ai/api/v1/api-keys/self" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch("https://inkbox.ai/api/v1/api-keys/self", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const key = await response.json();

import requests

response = requests.get(
    "https://inkbox.ai/api/v1/api-keys/self",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
key = response.json()

Update a key

Updating a key’s label or description is supported from the console. Scope, status, and other fields are immutable from any caller.

Revoke a key

POST /api-keys/self/revoke

Revokes the calling key. Revocation is permanent — to replace a key, mint a new one before revoking the old one. You can also revoke any key from the console. Revocation is idempotent for concurrent requests: if two requests authenticate with the same key before revocation completes, both return the same revoked record. Once revoked, the key no longer authenticates. Any later request with it, including another revoke call, returns 401 Unauthorized.

Response (200)

JSON

{
  "id": "ApiKey_8f3a2c91...",
  "status": "revoked",
  "revoked_at": "2026-05-08T17:30:00Z"
}

Code examples

curl -X POST "https://inkbox.ai/api/v1/api-keys/self/revoke" \
  -H "X-API-Key: YOUR_API_KEY"

await fetch("https://inkbox.ai/api/v1/api-keys/self/revoke", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});

import requests

requests.post(
    "https://inkbox.ai/api/v1/api-keys/self/revoke",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

Choosing a scope

Use agent-scoped keys for per-agent runtime credentials. Each agent gets its own key, narrowed to that identity.
Use admin-scoped keys for backend orchestration: provisioning agents, configuring custom domains and 10DLC, and managing contact rules and access grants.
Don’t ship admin-scoped keys to end-user agents. Mint an agent-scoped key per agent instead.

Agent signup — claim an agent identity and receive its initial API key
Identities — agent identity model
Signing keys — verify the authenticity of webhooks Inkbox sends to you
Webhooks — receive events from Inkbox

Get started

Capabilities

MCP

Webhooks

Signing keys

Skills

Integrations

API keys

Scopes

Admin-scoped

Agent-scoped

What each scope can do

Minting rules

Create an agent-scoped key

Response (201)

Inspect a key

Response (200)

Code examples

Update a key

Revoke a key

Response (200)

Code examples

Choosing a scope

​Scopes

​Admin-scoped

​Agent-scoped

​What each scope can do

​Minting rules

​Create an agent-scoped key

​Response (201)

​Inspect a key

​Response (200)

​Code examples

​Update a key

​Revoke a key

​Response (200)

​Code examples

​Choosing a scope

​Related

Scopes

Admin-scoped

Agent-scoped

What each scope can do

Minting rules

Create an agent-scoped key

Response (201)

Inspect a key

Response (200)

Code examples

Update a key

Revoke a key

Response (200)

Code examples

Choosing a scope

Related