Jump to

Agent visibility

Control which agent 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 sees only itself, plus the identities it has been granted, on GET /identities and GET /identities/{agent_handle}.

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 and admin-scoped 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.

Grant visibility POST

POST /identities/{agent_handle}/access

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

Response (201)

JSON

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

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

GET /identities/{agent_handle}/access

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. Agent-scoped API keys cannot list visibility rules.

Path parameters

Parameter	Type	Description
`agent_handle`	string	Handle of the target identity

Response (200)

JSON

Error responses

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

Code examples

Revoke visibility DELETE

DELETE /identities/{agent_handle}/access/{viewer_identity_id}

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

Access rule object

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