Inkbox

> # Documentation index
> Fetch the complete documentation index at: https://inkbox.ai/sitemap.xml
> Use this file to discover all available pages before exploring further.

---

# Note Access Control
description: Grant and revoke agent identity access to notes

---


# Note Access Control

Grant and revoke [agent identities](/docs/api/identities) access to a note. Notes use a **per-identity** model (no wildcard, unlike contacts). Humans (Clerk JWT) and admin API keys always see every note regardless of grants — the rules below only 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 an admin or JWT user.

---

## Grant identity access `POST`


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

> **Auth:** admin API key or Clerk JWT only. 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 admin or JWT) |
| 404 | Note or identity not found in your organization |
| 409 | Identity already has access to this note |

### Code examples

**cURL**

```bash
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"}'
```

**JavaScript**

```javascript
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();
```

**Python**

```python
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`


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**

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

**JavaScript**

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

**Python**

```python
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`


Revoke an identity's access to a note.

- Admin API keys and JWT humans 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 (humans 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**

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

**JavaScript**

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

**Python**

```python
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](/docs/api/identities) granted access (always non-null) |
| `created_at` | string | Creation timestamp (ISO 8601) |