Vault Keys

Vault keys protect your organization’s encryption key. There are two types:

Type	Purpose
`primary`	The main vault key used for day-to-day access
`recovery`	Backup keys generated during vault initialization, used to regain access if the primary key is lost

The server stores wrapped (encrypted) copies of the organization encryption key — one per vault key. It never has access to the unwrapped encryption key or the vault keys themselves.

List vault keys

GET /vault/keys

List all vault keys (metadata only — no wrapped key material). Optionally filter by key type.

Query parameters

Parameter	Type	Description
`type`	string	Filter by type: `primary` or `recovery`

Response (200)

JSON

[
  {
    "id": "k1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "key_type": "primary",
    "created_by": "user_2abc123",
    "status": "active",
    "invalidated_at": null,
    "created_at": "2026-03-01T12:00:00Z",
    "updated_at": "2026-03-01T12:00:00Z"
  },
  {
    "id": "k2b3c4d5-e6f7-8901-bcde-f12345678901",
    "key_type": "recovery",
    "created_by": "user_2abc123",
    "status": "active",
    "invalidated_at": null,
    "created_at": "2026-03-01T12:00:00Z",
    "updated_at": "2026-03-01T12:00:00Z"
  }
]

Code examples

curl -X GET "https://inkbox.ai/api/v1/vault/keys?type=primary" \
  -H "X-API-Key: YOUR_API_KEY"

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

import requests

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

Replace primary key

PUT /vault/keys/primary

Replace the primary vault key. You must prove possession of either the current primary key or a recovery code. When using a recovery code, that recovery key is consumed (invalidated) after the replacement.

Request body

Field	Type	Required	Description
`id`	UUID	Yes	New vault key ID (client-generated)
`wrapped_org_encryption_key`	string	Yes	Org encryption key wrapped with the new vault key (base64)
`auth_hash`	string	Yes	SHA-256 hash of the new vault key
`current_auth_hash`	string	One of	SHA-256 hash of the current primary key (proves current key possession)
`recovery_auth_hash`	string	One of	SHA-256 hash of a recovery code (consumes the recovery key)

Exactly one of current_auth_hash or recovery_auth_hash must be provided.

Request example (normal rotation)

JSON

{
  "id": "k3c4d5e6-f7a8-9012-cdef-234567890123",
  "wrapped_org_encryption_key": "eyJuZXdrZXki...",
  "auth_hash": "a1b2c3d4...",
  "current_auth_hash": "e5f6a7b8..."
}

Response (200)

JSON

{
  "id": "k3c4d5e6-f7a8-9012-cdef-234567890123",
  "key_type": "primary",
  "created_by": "user_2abc123",
  "status": "active",
  "invalidated_at": null,
  "created_at": "2026-03-20T10:00:00Z",
  "updated_at": "2026-03-20T10:00:00Z"
}

Error responses

Status	Description
400	Must provide exactly one of `current_auth_hash` or `recovery_auth_hash`
403	Invalid auth hash — key verification failed
404	Vault not found or recovery key not found

Code examples

curl -X PUT "https://inkbox.ai/api/v1/vault/keys/primary" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "k3c4d5e6-f7a8-9012-cdef-234567890123",
    "wrapped_org_encryption_key": "eyJuZXdrZXki...",
    "auth_hash": "a1b2c3d4...",
    "current_auth_hash": "e5f6a7b8..."
  }'

const response = await fetch(
  "https://inkbox.ai/api/v1/vault/keys/primary",
  {
      method: "PUT",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          id: "k3c4d5e6-f7a8-9012-cdef-234567890123",
          wrapped_org_encryption_key: "eyJuZXdrZXki...",
          auth_hash: "a1b2c3d4...",
          current_auth_hash: "e5f6a7b8...",
      }),
  }
);
const key = await response.json();

import requests

response = requests.put(
    "https://inkbox.ai/api/v1/vault/keys/primary",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "id": "k3c4d5e6-f7a8-9012-cdef-234567890123",
        "wrapped_org_encryption_key": "eyJuZXdrZXki...",
        "auth_hash": "a1b2c3d4...",
        "current_auth_hash": "e5f6a7b8...",
    },
)
key = response.json()

Revoke vault key

DELETE /vault/keys/{auth_hash}

Revoke a vault key by its auth hash. The key is invalidated and can no longer be used to unlock the vault. This operation is refused if the key is the last active key.

Path parameters

Parameter	Type	Description
`auth_hash`	string	SHA-256 hash of the vault key to revoke

Error responses

Status	Description
409	Cannot revoke the last active primary vault key
404	Vault key not found

Code examples

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

const authHash = "a1b2c3d4e5f6...";
await fetch(
  `https://inkbox.ai/api/v1/vault/keys/${authHash}`,
  {
      method: "DELETE",
      headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

import requests

auth_hash = "a1b2c3d4e5f6..."
requests.delete(
    f"https://inkbox.ai/api/v1/vault/keys/{auth_hash}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

Vault key object

Field	Type	Description
`id`	UUID	Unique vault key identifier
`key_type`	string	Key type: `primary` or `recovery`
`created_by`	string	User ID that created this key
`status`	string	Lifecycle status: `active`, `invalidated`
`invalidated_at`	string \| null	When the key was revoked (ISO 8601), or `null` if active
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)

Agent signup API

Agent identity API

Agent2Agent API

Message retries

Mail API

Phone API

iMessage API

Slack API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

List vault keys

Query parameters

Response (200)

Code examples

Replace primary key

Request body

Request example (normal rotation)

Response (200)

Error responses

Code examples

Revoke vault key

Path parameters

Error responses

Code examples

Vault key object

​List vault keys

​Query parameters

​Response (200)

​Code examples

​Replace primary key

​Request body

​Request example (normal rotation)

​Response (200)

​Error responses

​Code examples

​Revoke vault key

​Path parameters

​Error responses

​Code examples

​Vault key object

List vault keys

Query parameters

Response (200)

Code examples

Replace primary key

Request body

Request example (normal rotation)

Response (200)

Error responses

Code examples

Revoke vault key

Path parameters

Error responses

Code examples

Vault key object