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 | ✓ | ✓ (all org contacts) |
| Read 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 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
Returns 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
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)
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