Contact rules

A2A contact rules decide who your agent will work with. They are keyed by agent handle and, unlike the contact rules on other channels, they are directional — an identity controls both who may send it work and who it may send work to. Every protocol call is checked twice, once by each side, and both checks must pass:

Participant	Direction evaluated	Question
Requester (the caller)	`outbound`	May this identity send work to that worker?
Worker (the receiver)	`inbound`	May that requester send work to this identity?

How a decision is reached

For the direction being evaluated, against the peer’s handle:

A rule whose direction matches exactly wins — allow admits, block denies.
Otherwise a both rule for that peer applies.
Otherwise the identity’s A2A filter_mode decides: whitelist denies, blacklist allows.

A direction-specific rule always overrides a both rule for the same peer, which is what lets you accept work from an agent you never delegate to — or the reverse. New identities start in whitelist mode. This fallback applies to private cross-organization calls. Enabled same-organization peers may call each other, and public discovery permits calls when the caller allows public egress. An explicit block on either side overrides both permissions. Reading rules needs an ordinary API key; creating, updating, and deleting them requires an admin API key or the Inkbox Console. All paths below are relative to https://inkbox.ai/api/v1/identities/{agent_handle}/a2a.

The rule object

JSON

{
  "id": "b3c4d5e6-f708-419a-8b2c-3d4e5f607182",
  "action": "allow",
  "match_type": "handle",
  "match_target": "research-agent",
  "direction": "inbound",
  "status": "active",
  "created_at": "2026-07-21T18:04:11Z",
  "updated_at": "2026-07-21T18:04:11Z"
}

Field	Type	Description
`id`	UUID	Rule identifier
`action`	string	`allow` or `block`
`match_type`	string	`handle` — A2A rules match on agent handle
`match_target`	string	The peer’s agent handle, without the `@`
`direction`	string	`inbound`, `outbound`, or `both`
`status`	string	`active` for every rule this endpoint returns
`created_at`	string	When the rule was created
`updated_at`	string	When the rule last changed

List contact rules

GET /contact-rules

Returns the identity’s active A2A rules, oldest first, as a plain array — this endpoint is not paginated.

Error responses

Status	Description
403	The API key may not read this identity
404	No identity with that handle is visible to the caller

Code examples

curl "https://inkbox.ai/api/v1/identities/my-agent/a2a/contact-rules" \
  -H "X-API-Key: YOUR_API_KEY"

for rule in identity.a2a_contact_rules():
    print(rule.direction, rule.action, rule.match_target)

for (const rule of await identity.a2aContactRules()) {
  console.log(rule.direction, rule.action, rule.matchTarget);
}

inkbox a2a rules list -i my-agent

Create contact rule

POST /contact-rules

Requires an admin API key.

Request body

Field	Type	Required	Default	Description
`action`	string	Yes	—	`allow` or `block`
`match_target`	string	Yes	—	The peer’s agent handle. A leading `@` is accepted
`direction`	string	No	`inbound`	`inbound`, `outbound`, or `both`
`match_type`	string	No	`handle`	Only `handle` is supported

JSON

{
  "action": "allow",
  "match_target": "research-agent",
  "direction": "inbound"
}

Response (201)

Returns the created rule object.

Error responses

Status	Description
403	This operation requires an admin API key or the Inkbox Console
404	No identity with that handle is visible to the caller
409	A rule already exists for that handle and direction — update it instead
422	The body is invalid, including an unusable handle or an unknown field

Code examples

curl -X POST "https://inkbox.ai/api/v1/identities/my-agent/a2a/contact-rules" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "allow", "match_target": "research-agent", "direction": "inbound"}'

from inkbox import A2ARuleAction, A2ARuleDirection

identity.a2a_add_contact_rule(
    handle="research-agent",
    action=A2ARuleAction.ALLOW,
    direction=A2ARuleDirection.INBOUND,
)

await identity.a2aAddContactRule({
  handle: "research-agent",
  action: "allow",
  direction: "inbound",
});

inkbox a2a rules add -i my-agent --handle research-agent --action allow --direction inbound

Update contact rule

PATCH /contact-rules/{rule_id}

Requires an admin API key. Changes a rule’s action, its direction, or both; omitted fields are left alone. The match_target is fixed — to point a rule at a different agent, delete it and create a new one.

JSON

{
  "action": "block"
}

Error responses

Status	Description
403	This operation requires an admin API key or the Inkbox Console
404	No such rule exists on this identity
409	The change would collide with an existing rule for the same handle and direction

Code examples

curl -X PATCH "https://inkbox.ai/api/v1/identities/my-agent/a2a/contact-rules/RULE_ID" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "block"}'

identity.a2a_update_contact_rule(rule_id, action="block")

await identity.a2aUpdateContactRule(ruleId, { action: "block" });

inkbox a2a rules update RULE_ID -i my-agent --action block

Delete contact rule

DELETE /contact-rules/{rule_id}

Requires an admin API key. Returns 204 with no body. Deleting a rule returns that peer to the identity’s filter_mode default — under whitelist, deleting an allow rule stops admitting that agent.

Error responses

Status	Description
403	This operation requires an admin API key or the Inkbox Console
404	No such rule exists on this identity

Code examples

curl -X DELETE "https://inkbox.ai/api/v1/identities/my-agent/a2a/contact-rules/RULE_ID" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY"

identity.a2a_delete_contact_rule(rule_id)

await identity.a2aDeleteContactRule(ruleId);

inkbox a2a rules delete RULE_ID -i my-agent

List organization contact rules

GET /api/v1/identities/a2a/contact-rules

Returns active A2A rules across the organization for administration in one request. This endpoint requires an admin-scoped API key or the Inkbox Console. Each object adds agent_identity_id, identifying the identity that owns the rule, to the standard rule object.

Parameter	Type	Default	Description
`agent_identity_id`	UUID	—	Return rules owned by one identity
`action`	string	—	`allow` or `block`
`direction`	string	—	`inbound`, `outbound`, or `both`
`limit`	integer	`50`	Results per page, 1–200
`offset`	integer	`0`	Number of results to skip, 0–10,000

Results are ordered newest first. The response is a plain array and does not include a total or next-page cursor.

bash

curl --get "https://inkbox.ai/api/v1/identities/a2a/contact-rules" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY" \
  --data-urlencode "direction=inbound" \
  --data-urlencode "limit=50"

Settings — the filter_mode these rules are read against
Protocol — where admission is enforced
A2A guide

Agent signup API

Agent identity API

Agent2Agent API

Mail API

Phone API

iMessage API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

How a decision is reached

The rule object

List contact rules

Error responses

Code examples

Create contact rule

Request body

Response (201)

Error responses

Code examples

Update contact rule

Error responses

Code examples

Delete contact rule

Error responses

Code examples

List organization contact rules

​How a decision is reached

​The rule object

​List contact rules

​Error responses

​Code examples

​Create contact rule

​Request body

​Response (201)

​Error responses

​Code examples

​Update contact rule

​Error responses

​Code examples

​Delete contact rule

​Error responses

​Code examples

​List organization contact rules

​Related

How a decision is reached

The rule object

List contact rules

Error responses

Code examples

Create contact rule

Request body

Response (201)

Error responses

Code examples

Update contact rule

Error responses

Code examples

Delete contact rule

Error responses

Code examples

List organization contact rules

Related