Signing keys

Each agent identity has its own signing key, used to verify the webhooks and WebSocket upgrades for that identity’s mailbox, phone number, and iMessage traffic. Verify incoming payloads for an identity’s mail and phone channels with that identity’s key. Until an identity has a key, its webhooks and WebSocket connections are sent unsigned. Once a key exists, all of that identity’s webhooks and WebSocket upgrades are signed automatically. The plaintext key is returned only once when created or rotated. Store it securely — it cannot be retrieved again. Your existing webhooks continue to verify with the same secret. Signing keys are complementary to a subscription’s optional delivery auth_token: the signature is per identity and proves a payload came from Inkbox unmodified, while the bearer token is per subscription and authenticates Inkbox to endpoints that require an Authorization header. Setting one does not affect the other.

How an identity first gets its key

A brand-new agent identity has no signing key. There are two ways one comes into existence:

Automatically, on the first subscription. The first webhook subscription you create for a keyless identity returns that identity’s signing secret once, in the signing_key field of the create response. Store it then — it isn’t shown again. See Subscriptions.
Explicitly, via the POST route below. Call POST /identities/{agent_handle}/signing-key to mint a key up front (or to rotate an existing one).

Get signing key status

GET /identities/{agent_handle}/signing-key

Report whether this agent identity has a signing key configured. Does not return the secret.

Response (200)

JSON

{
  "configured": true,
  "created_at": "2026-03-13T15:30:45Z"
}

Field	Type	Description
`configured`	boolean	`true` if this identity has a signing key.
`created_at`	string \| null	Timestamp the key was created or last rotated (ISO 8601); `null` when not configured.

Code examples

curl -X GET "https://inkbox.ai/api/v1/identities/my-agent/signing-key" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  "https://inkbox.ai/api/v1/identities/my-agent/signing-key",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { configured, created_at } = await response.json();

import requests

response = requests.get(
    "https://inkbox.ai/api/v1/identities/my-agent/signing-key",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = response.json()

Create or rotate signing key

POST /identities/{agent_handle}/signing-key

Create a signing key for this agent identity, or rotate the existing one. On the first call a new key is generated. On subsequent calls the old key is replaced with a fresh one.

Response (201)

JSON

{
  "signing_key": "7K9x2mP4qR8vT1wY3zA5bC6dE0fG...",
  "created_at": "2026-03-13T15:30:45Z"
}

Field	Type	Description
`signing_key`	string	Plaintext signing key. Store this securely — it is only returned once.
`created_at`	string	Timestamp of creation or rotation (ISO 8601).

Error responses

Status	Description
`503`	Webhook signing is not configured on the server.

Code examples

curl -X POST "https://inkbox.ai/api/v1/identities/my-agent/signing-key" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  "https://inkbox.ai/api/v1/identities/my-agent/signing-key",
  {
      method: "POST",
      headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);
const { signing_key, created_at } = await response.json();
// Store signing_key securely — it cannot be retrieved again

import requests

response = requests.post(
    "https://inkbox.ai/api/v1/identities/my-agent/signing-key",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = response.json()
# Store data["signing_key"] securely — it cannot be retrieved again

Deprecated: org-level signing key

The org-level endpoints POST /signing-keys and GET /signing-keys are deprecated. Their responses carry a Link header pointing at the per-identity route above. Move to …/identities/{agent_handle}/signing-key. While they remain available, behavior depends on the caller’s auth scope:

Endpoint	Agent-scoped API key	Admin API key, or manage from the Inkbox Console
`POST /signing-keys`	Rotates that one identity’s key (returns the secret once).	Returns `409` — rotate a specific identity via `POST /identities/{agent_handle}/signing-key`.
`GET /signing-keys`	Reports that identity’s status.	Reports an org-aggregate status: `configured` is `true` if any identity in the org has a key.

Verifying webhook signatures

Once you have an identity’s signing key, use it to verify incoming webhook payloads for that identity. See:

Get started

Capabilities

API keys

MCP

Webhooks

Skills

Integrations

Signing keys

How an identity first gets its key

Get signing key status

Response (200)

Code examples

Create or rotate signing key

Response (201)

Error responses

Code examples

Deprecated: org-level signing key

Verifying webhook signatures

​How an identity first gets its key

​Get signing key status

​Response (200)

​Code examples

​Create or rotate signing key

​Response (201)

​Error responses

​Code examples

​Deprecated: org-level signing key

​Verifying webhook signatures

How an identity first gets its key

Get signing key status

Response (200)

Code examples

Create or rotate signing key

Response (201)

Error responses

Code examples

Deprecated: org-level signing key

Verifying webhook signatures