Vault Secrets

A vault secret is an encrypted credential stored in your organization’s vault. The server only stores ciphertext — all encryption and decryption happens client-side using your vault key. Each secret has a secret_type that determines its payload structure: login, api_key, key_pair, ssh_key, or other. Login secrets can optionally include a TOTP configuration for two-factor authentication.

Create secret

POST /vault/secrets

Store a new encrypted secret. The encrypted_payload field contains the client-side encrypted credential data.

Request body

Field	Type	Required	Description
`id`	UUID	Yes	Client-generated secret ID. Generate it before encrypting because it is used as additional authenticated data.
`name`	string	Yes	Human-readable name for this secret. 1–255 chars.
`description`	string	No	Optional description
`secret_type`	string	Yes	One of: `login`, `api_key`, `key_pair`, `ssh_key`, `other`
`encrypted_payload`	string	Yes	Client-side encrypted payload (base64)

Request example

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Analytics API",
  "description": "API key for the analytics service",
  "secret_type": "api_key",
  "encrypted_payload": "eyJpdiI6Ik..."
}

Response (201)

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Analytics API",
  "description": "API key for the analytics service",
  "secret_type": "api_key",
  "access": [],
  "created_at": "2026-03-15T12:00:00Z",
  "updated_at": "2026-03-15T12:00:00Z"
}

Error responses

Status	Description
403	Organization ID missing from token
422	Missing or invalid fields

Code examples

curl -X POST "https://inkbox.ai/api/v1/vault/secrets" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Analytics API",
    "secret_type": "api_key",
    "encrypted_payload": "eyJpdiI6Ik..."
  }'

const response = await fetch("https://inkbox.ai/api/v1/vault/secrets", {
  method: "POST",
  headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
  },
  body: JSON.stringify({
      id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      name: "Analytics API",
      secret_type: "api_key",
      encrypted_payload: "eyJpdiI6Ik...",
  }),
});
const secret = await response.json();

import requests

response = requests.post(
    "https://inkbox.ai/api/v1/vault/secrets",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Analytics API",
        "secret_type": "api_key",
        "encrypted_payload": "eyJpdiI6Ik...",
    },
)
secret = response.json()

List secrets

GET /vault/secrets

List all secrets (metadata only — no encrypted payloads). Optionally filter by secret type. Each secret carries its inlined access rules — the same rows List access returns — so you can render who can read each secret without a per-secret follow-up call. access is empty on create/update responses.

Query parameters

Parameter	Type	Description
`secret_type`	string	Filter by type: `login`, `api_key`, `key_pair`, `ssh_key`, `other`
`limit`	integer	Maximum rows to return (1–200). Omit to return all visible secrets.
`offset`	integer	Rows to skip (0–10,000). Defaults to `0`.

Response (200)

JSON

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Analytics API",
    "description": "API key for the analytics service",
    "secret_type": "api_key",
    "access": [
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "vault_secret_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "identity_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
        "created_at": "2026-03-16T08:00:00Z"
      }
    ],
    "created_at": "2026-03-15T12:00:00Z",
    "updated_at": "2026-03-15T12:00:00Z"
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Dashboard Login",
    "description": null,
    "secret_type": "login",
    "access": [],
    "created_at": "2026-03-10T09:30:00Z",
    "updated_at": "2026-03-10T09:30:00Z"
  }
]

Code examples

curl -X GET "https://inkbox.ai/api/v1/vault/secrets?secret_type=api_key" \
  -H "X-API-Key: YOUR_API_KEY"

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

import requests

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

Get secret

GET /vault/secrets/{secret_id}

Get a single secret including its encrypted_payload. Use this to fetch the ciphertext for client-side decryption. The response inlines the secret’s access rules, same as the list read.

Path parameters

Parameter	Type	Description
`secret_id`	UUID	Secret ID

Response (200)

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Analytics API",
  "description": "API key for the analytics service",
  "secret_type": "api_key",
  "access": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "vault_secret_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "identity_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "created_at": "2026-03-16T08:00:00Z"
    }
  ],
  "encrypted_payload": "eyJpdiI6Ik...",
  "created_at": "2026-03-15T12:00:00Z",
  "updated_at": "2026-03-15T12:00:00Z"
}

Code examples

curl -X GET "https://inkbox.ai/api/v1/vault/secrets/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: YOUR_API_KEY"

const secretId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
  `https://inkbox.ai/api/v1/vault/secrets/${secretId}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const secret = await response.json();

import requests

secret_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.get(
    f"https://inkbox.ai/api/v1/vault/secrets/{secret_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
secret = response.json()

Update secret

PATCH /vault/secrets/{secret_id}

Update a secret’s name, description, or encrypted payload. Only supplied fields are modified.

Path parameters

Parameter	Type	Description
`secret_id`	UUID	Secret ID

Request body

Field	Type	Required	Description
`name`	string	No	Updated name. 1–255 chars.
`description`	string	No	Updated description
`encrypted_payload`	string	No	Updated client-side encrypted payload (base64)

Request example

JSON

{
  "name": "Analytics API (rotated)",
  "encrypted_payload": "eyJuZXdpdiI6..."
}

Response (200)

Returns the updated secret object (without encrypted_payload).

Code examples

curl -X PATCH "https://inkbox.ai/api/v1/vault/secrets/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Analytics API (rotated)"}'

const secretId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
  `https://inkbox.ai/api/v1/vault/secrets/${secretId}`,
  {
      method: "PATCH",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({ name: "Analytics API (rotated)" }),
  }
);
const secret = await response.json();

import requests

secret_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.patch(
    f"https://inkbox.ai/api/v1/vault/secrets/{secret_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Analytics API (rotated)"},
)
secret = response.json()

Delete secret

DELETE /vault/secrets/{secret_id}

Delete a secret. Returns 204 No Content on success.

Path parameters

Parameter	Type	Description
`secret_id`	UUID	Secret ID

Code examples

curl -X DELETE "https://inkbox.ai/api/v1/vault/secrets/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: YOUR_API_KEY"

const secretId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
await fetch(
  `https://inkbox.ai/api/v1/vault/secrets/${secretId}`,
  {
      method: "DELETE",
      headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

import requests

secret_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
requests.delete(
    f"https://inkbox.ai/api/v1/vault/secrets/{secret_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

Secret object

Field	Type	Description
`id`	UUID	Unique secret identifier
`name`	string	Human-readable name
`description`	string \| null	Optional description
`secret_type`	string	Type: `login`, `api_key`, `key_pair`, `ssh_key`, `other`
`access`	array	Access rules identifying the agent identities that can read this secret. Empty when no identities have access and on create or update responses.
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)

Secret detail object

Extends the secret object, including its access rules, with the encrypted payload. Returned by the get endpoint.

Field	Type	Description
…all secret fields
`encrypted_payload`	string	Client-side encrypted payload (base64)

For the plaintext structure of the encrypted_payload, see Payload schemas.

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

Create secret

Request body

Request example

Response (201)

Error responses

Code examples

List secrets

Query parameters

Response (200)

Code examples

Get secret

Path parameters

Response (200)

Code examples

Update secret

Path parameters

Request body

Request example

Response (200)

Code examples

Delete secret

Path parameters

Code examples

Secret object

Secret detail object

​Create secret

​Request body

​Request example

​Response (201)

​Error responses

​Code examples

​List secrets

​Query parameters

​Response (200)

​Code examples

​Get secret

​Path parameters

​Response (200)

​Code examples

​Update secret

​Path parameters

​Request body

​Request example

​Response (200)

​Code examples

​Delete secret

​Path parameters

​Code examples

​Secret object

​Secret detail object

Create secret

Request body

Request example

Response (201)

Error responses

Code examples

List secrets

Query parameters

Response (200)

Code examples

Get secret

Path parameters

Response (200)

Code examples

Update secret

Path parameters

Request body

Request example

Response (200)

Code examples

Delete secret

Path parameters

Code examples

Secret object

Secret detail object