Note Access Control

Grant and revoke agent identities access to a note. Notes use explicit per-identity grants; contacts have separate visibility and communication choices. Users in the Inkbox Console and admin-scoped API keys always see every note regardless of grants. The rules below apply to scoped agent keys. Agent-created notes are auto-granted to the creating identity on POST /notes. All other grants must be added explicitly by a user in the Inkbox Console or a caller using an admin-scoped API key.

Grant identity access

POST /notes/{note_id}/access

Grant an agent identity read + CRUD access to a note.

Auth: admin-scoped API key, or as a user in the Inkbox Console. A scoped agent cannot grant itself or a peer.

Path parameters

Parameter	Type	Description
`note_id`	UUID	Note ID

Request body

Field	Type	Required	Description
`identity_id`	UUID	Yes	Identity to grant access to (must belong to the same organization)

Response (201)

JSON

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

Error responses

Status	Description
403	Caller is a scoped agent (grants require an admin-scoped API key or a Console user)
404	Note or identity not found in your organization
409	Identity already has access to this note

Code examples

curl -X POST "https://inkbox.ai/api/v1/notes/NOTE_ID/access" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"}'

const response = await fetch(
  `https://inkbox.ai/api/v1/notes/${noteId}/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

response = requests.post(
    f"https://inkbox.ai/api/v1/notes/{note_id}/access",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"},
)
rule = response.json()

List access rules

GET /notes/{note_id}/access

List the identities granted access to a note. A scoped agent without visibility on the note 404s before reaching the grant listing.

Path parameters

Parameter	Type	Description
`note_id`	UUID	Note ID

Response (200)

JSON

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

Code examples

curl -X GET "https://inkbox.ai/api/v1/notes/NOTE_ID/access" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  `https://inkbox.ai/api/v1/notes/${noteId}/access`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const rules = await response.json();

import requests

response = requests.get(
    f"https://inkbox.ai/api/v1/notes/{note_id}/access",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
rules = response.json()

Revoke identity access

DELETE /notes/{note_id}/access/{identity_id}

Revoke an identity’s access to a note.

Admin-scoped API keys and users in the Inkbox Console may revoke any identity — including the original creator. created_by is a pure audit stamp; revoking the creator’s grant makes the note agent-invisible (Console users still see it).
A claimed agent may only revoke its own grant.

Path parameters

Parameter	Type	Description
`note_id`	UUID	Note ID
`identity_id`	UUID	Identity whose grant to revoke

Response

204 No Content on success.

Error responses

Status	Description
403	Claimed agent attempted to revoke another identity
404	Access rule not found

Code examples

curl -X DELETE "https://inkbox.ai/api/v1/notes/NOTE_ID/access/IDENTITY_ID" \
  -H "X-API-Key: YOUR_API_KEY"

await fetch(
  `https://inkbox.ai/api/v1/notes/${noteId}/access/${identityId}`,
  {
      method: "DELETE",
      headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

import requests

requests.delete(
    f"https://inkbox.ai/api/v1/notes/{note_id}/access/{identity_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

Access rule object

Field	Type	Description
`id`	UUID	Unique access rule identifier
`note_id`	UUID	The note this rule grants access to
`identity_id`	UUID	The agent identity granted access (always non-null)
`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

Note Access Control

Grant identity access

Path parameters

Request body

Response (201)

Error responses

Code examples

List access rules

Path parameters

Response (200)

Code examples

Revoke identity access

Path parameters

Response

Error responses

Code examples

Access rule object

​Grant identity access

​Path parameters

​Request body

​Response (201)

​Error responses

​Code examples

​List access rules

​Path parameters

​Response (200)

​Code examples

​Revoke identity access

​Path parameters

​Response

​Error responses

​Code examples

​Access rule object

Grant identity access

Path parameters

Request body

Response (201)

Error responses

Code examples

List access rules

Path parameters

Response (200)

Code examples

Revoke identity access

Path parameters

Response

Error responses

Code examples

Access rule object