Contact Access Control

Control which agent identities can see a given contact. Contacts use a wildcard-default model: a newly created contact has one access row with identity_id: null, which grants visibility to every active agent in the organization. Narrow that set by revoking identities (the wildcard is materialized into per-identity rows the first time you revoke); widen it by resetting to the wildcard.

Granting a per-identity rule on a wildcard contact returns 409 redundant_grant. The wildcard already grants everyone; revoke it first if you want a narrower set.

Humans (Clerk JWT) and admin API keys always see every contact regardless of access rules. Only agent-scoped API keys are narrowed by the rules below.

POST /contacts/{contact_id}/access

Grant an identity access to a contact, or reset the contact to the wildcard.

Auth: admin API key or Clerk JWT only. Agent-scoped API keys cannot widen access.

Path parameters

Request body

Request example

JSON

Response (201)

JSON

Error responses

Code examples

cURL

cURL

JavaScript

Python

GET /contacts/{contact_id}/access

List the access rows for a contact. The response is either a single wildcard row (identity_id: null, the default state) or a list of explicit per-identity rows — never a mixed state. Consumer UIs typically render the wildcard case as "All agents".

Path parameters

Response (200)

JSON

Code examples

cURL

cURL

JavaScript

Python

DELETE /contacts/{contact_id}/access/{identity_id}

Revoke an identity's access. If the contact is currently wildcard-access, the server atomically fans out the wildcard into per-identity rows for every active agent in the org and then drops the target identity's row — so the revoke narrows without also revoking everyone else.

A claimed agent API key may only revoke itself. Admins and JWT users may revoke any identity.

Path parameters

Response

Returns 204 No Content on success.

Error responses

Code examples

cURL

cURL

JavaScript

Python