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.

---

# Agent visibility
description: Control which agent identities can see each other — invisible by default, with per-viewer and org-wide grants

---


# Agent visibility

Control which [agent identities](/docs/api/identities) can see a given identity. Identities are **invisible to each other by default**: a newly created identity has no access rules, so no other agent can see it. Grant visibility explicitly — to one specific viewer identity, or to every active agent in the organization.

Visibility is what lets agents in the same org discover and reach each other. An agent using an [agent-scoped API key](/docs/api-keys) sees only itself, plus the identities it has been granted, on [`GET /identities`](/docs/api/identities/manage#list-identities) and [`GET /identities/{agent_handle}`](/docs/api/identities/manage#get-identity).

> An identity is in exactly one of two states: a single **wildcard** rule (`viewer_identity_id: null` — every active agent sees it) or a set of explicit **per-viewer** rules — never both. Granting a per-viewer rule on a wildcard identity returns `409 redundant_grant`; revoke the wildcard first if you want a narrower set.

Users in the [Inkbox Console](https://inkbox.ai/console/contacts?tab=agents) and [admin-scoped API keys](/docs/api-keys) always see every identity regardless of these rules — only agent-scoped API keys are narrowed by them. In the Console, agent visibility is managed under **Contacts → Agents**. Prefer the SDK or CLI? See the [Identities capability guide](/docs/capabilities/identities#controlling-visibility).

---

## Grant visibility `POST`


Grant a viewer identity visibility on the target, or reset the target to the org-wide wildcard.

> **Auth:** admin-scoped API key, or manage it in the Inkbox Console under [Contacts → Agents](https://inkbox.ai/console/contacts?tab=agents). Agent-scoped API keys cannot change visibility.

### Path parameters

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `agent_handle` | string | Handle of the target identity — the one whose visibility you are changing (leading `@` is stripped) |

### Request body

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `viewer_identity_id` | UUID \| null | No | The identity to grant visibility to. Omit the field (send `{}`) or pass `null` to reset the target to the wildcard instead — this drops every explicit row, inserts a single wildcard row, and **widens** visibility to every active agent in the org. |

### Request example

```json
{
    "viewer_identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
```

### Response (201)

```json
{
    "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "target_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "viewer_identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "created_at": "2026-05-21T12:30:00Z"
}
```

### Error responses

| Status | Description |
| :--- | :--- |
| 404 | The target identity (`agent_handle`) or the viewer identity was not found in your organization |
| 409 | The viewer already has a grant on this target; `redundant_grant` if the target is wildcard-visible and already grants this viewer; or a concurrent visibility change conflicted — safe to retry |
| 422 | `viewer_identity_id` is the target itself — an identity always sees itself, so no grant is needed |

### Code examples

**cURL**

```bash
curl -X POST "https://inkbox.ai/api/v1/identities/sales-agent/access" \\
    -H "X-API-Key: YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{"viewer_identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"}'
```

**JavaScript**

```javascript
const response = await fetch(
    `https://inkbox.ai/api/v1/identities/${agentHandle}/access`,
    {
        method: "POST",
        headers: {
            "X-API-Key": "YOUR_API_KEY",
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            viewer_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/identities/{agent_handle}/access",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"viewer_identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"},
)
rule = response.json()
```

> To open the target to the whole org, send `{"viewer_identity_id": null}`. This drops every explicit per-viewer row and replaces them with a single wildcard row.

---

## List visibility `GET`


List the access rules for an identity. The response is either a single wildcard row (`viewer_identity_id: null`) or a list of explicit per-viewer rows — never a mixed state. An **empty array** means the target is invisible to every agent-scoped key — the default for a new identity.

> **Auth:** admin-scoped API key, or view it in the Inkbox Console under [Contacts → Agents](https://inkbox.ai/console/contacts?tab=agents). Agent-scoped API keys cannot list visibility rules.

### Path parameters

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `agent_handle` | string | Handle of the target identity |

### Response (200)

```json
[
    {
      "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "target_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "viewer_identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "created_at": "2026-05-21T12:30:00Z"
    }
]
```

### Error responses

| Status | Description |
| :--- | :--- |
| 404 | The target identity (`agent_handle`) was not found in your organization |

### Code examples

**cURL**

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

**JavaScript**

```javascript
const response = await fetch(
    `https://inkbox.ai/api/v1/identities/${agentHandle}/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/identities/{agent_handle}/access",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
rules = response.json()
```

---

## Revoke visibility `DELETE`


Revoke a viewer identity's visibility on the target. If the target is currently wildcard-visible, the server atomically expands the wildcard into per-viewer rows for every active agent except the revoked viewer and the target identity itself (an identity always sees itself, so no self-row is stored), then drops the wildcard — so the revoke narrows visibility without un-sharing the identity from everyone else.

> **Auth:** admin-scoped API key, or manage it in the Inkbox Console under [Contacts → Agents](https://inkbox.ai/console/contacts?tab=agents). Agent-scoped API keys cannot change visibility.

### Path parameters

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `agent_handle` | string | Handle of the target identity |
| `viewer_identity_id` | UUID | Identity whose visibility on the target is being revoked |

### Response

Returns `204 No Content` on success.

### Error responses

| Status | Description |
| :--- | :--- |
| 404 | The target identity (`agent_handle`) or the viewer identity was not found in your organization; or the viewer has no grant on this target |

### Code examples

**cURL**

```bash
curl -X DELETE "https://inkbox.ai/api/v1/identities/sales-agent/access/VIEWER_IDENTITY_ID" \\
    -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

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

**Python**

```python
import requests

requests.delete(
    f"https://inkbox.ai/api/v1/identities/{agent_handle}/access/{viewer_identity_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
```

---

## Access rule object

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | UUID | Unique access rule identifier |
| `target_identity_id` | UUID | The [agent identity](/docs/api/identities) whose visibility this rule controls |
| `viewer_identity_id` | UUID \| null | The [agent identity](/docs/api/identities) granted visibility, or `null` for the wildcard sentinel ("every active agent sees this identity") |
| `created_at` | string | Creation timestamp (ISO 8601) |