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 access grants on contacts and notes.
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 and notes | ✓ (all org resources) | ✓ (only what the identity is granted access to) |
| Manage custom email domains | ✓ | — |
| Manage 10DLC compliance | ✓ | — |
| Manage mail and phone contact rules | ✓ | — |
| Grant access to contacts and 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.
Inspect a key GET
GET /api-keys/selfReturns metadata for the calling key. The plaintext value is never returned again after creation.
Response (200)
JSONscoped_identity_id is null for admin-scoped keys, or an identity ID for agent-scoped keys.
Code examples
cURLUpdate 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
POST /api-keys/self/revokeRevokes 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.
Response (200)
JSONCode examples
cURLChoosing 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