Access Control

Control which agent identities can access specific vault secrets. Access rules are per-secret — you grant an identity access to one secret at a time. An identity without an access rule for a given secret cannot read it.

Grant identity access

POST /vault/secrets/{secret_id}/access

Grant an agent identity access to a specific secret.

Path parameters

Parameter	Type	Description
`secret_id`	UUID	Secret ID

Request body

Field	Type	Required	Description
`identity_id`	UUID	Yes	ID of the agent identity to grant access to

Request example

JSON

{
  "identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

Response (201)

JSON

{
  "id": "r1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "vault_secret_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "created_at": "2026-03-15T12:30:00Z"
}

Error responses

Status	Description
403	Organization ID missing from token
404	Secret or identity not found
409	Identity already has access to this secret

Code examples

curl -X POST "https://inkbox.ai/api/v1/vault/secrets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"}'

const secretId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
  `https://inkbox.ai/api/v1/vault/secrets/${secretId}/access`,
  {
      method: "POST",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          identity_id: "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      }),
  }
);
const rule = await response.json();

import requests

secret_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.post(
    f"https://inkbox.ai/api/v1/vault/secrets/{secret_id}/access",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"},
)
rule = response.json()

List access rules

GET /vault/secrets/{secret_id}/access

List all identity access rules for a secret.

Path parameters

Parameter	Type	Description
`secret_id`	UUID	Secret ID

Response (200)

JSON

[
  {
    "id": "r1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "vault_secret_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "created_at": "2026-03-15T12:30:00Z"
  }
]

Code examples

curl -X GET "https://inkbox.ai/api/v1/vault/secrets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access" \
  -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}/access`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const rules = 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}/access",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
rules = response.json()

Revoke identity access

DELETE /vault/secrets/{secret_id}/access/{identity_id}

Revoke an identity’s access to a secret. Returns 204 No Content on success.

Path parameters

Parameter	Type	Description
`secret_id`	UUID	Secret ID
`identity_id`	UUID	Identity ID to revoke access from

Code examples

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

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

import requests

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

Access rule object

Field	Type	Description
`id`	UUID	Unique access rule identifier
`vault_secret_id`	UUID	The secret this rule grants access to
`identity_id`	UUID	The agent identity that has access
`created_at`	string	Creation 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

Access Control

Grant identity access

Path parameters

Request body

Request example

Response (201)

Error responses

Code examples

List access rules

Path parameters

Response (200)

Code examples

Revoke identity access

Path parameters

Code examples

Access rule object

​Grant identity access

​Path parameters

​Request body

​Request example

​Response (201)

​Error responses

​Code examples

​List access rules

​Path parameters

​Response (200)

​Code examples

​Revoke identity access

​Path parameters

​Code examples

​Access rule object

Grant identity access

Path parameters

Request body

Request example

Response (201)

Error responses

Code examples

List access rules

Path parameters

Response (200)

Code examples

Revoke identity access

Path parameters

Code examples

Access rule object