Inkbox

> # Documentation index
> Fetch the complete documentation index at: https://inkbox.ai/sitemap.xml
> Use this file to discover all available pages before exploring further.

---

# API keys
description: Admin-scoped vs agent-scoped API keys, what each can do, and how to mint, inspect, and revoke them.

---


# 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](/docs/get-started/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](/docs/capabilities/email/custom-email-domains) | ✓ | — |
| Manage [10DLC compliance](/docs/capabilities/phone/10dlc) | ✓ | — |
| Manage [mail](/docs/api/mail/contact-rules) and [phone](/docs/api/phone/contact-rules) contact rules | ✓ | — |
| Grant access to [contacts](/docs/api/contacts/access) and [notes](/docs/api/notes/access) | ✓ | — |
| 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](/docs/get-started/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)

```json
{
    "id": "ApiKey_8f3a2c91...",
    "scoped_identity_id": null,
    "status": "active",
    "display_prefix": "ink_live_",
    "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**

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

**JavaScript**

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

**Python**

```python
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`


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.

### Response (200)

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

### Code examples

**cURL**

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

**JavaScript**

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

**Python**

```python
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.

---

## Related

- [Agent signup](/docs/get-started/agent-signup) — claim an agent identity and receive its initial API key
- [Identities](/docs/capabilities/identities) — agent identity model
- [Signing keys](/docs/signing-keys) — verify the authenticity of webhooks Inkbox sends to you
- [Webhooks](/docs/webhooks) — receive events from Inkbox