Bind an API key or inbox to an agent

Endpoint

POST https://api.dairo.app/v1/agents/{id}/bindings

Attaches an API key and/or an inbox you own to this passport, so every message that key authenticates — or that is sent from that inbox — is attributed to the agent and carries a signed X-Dairo-Provenance header recipients can verify. Address the passport by id (uuid) or portable agentId (agt_...). Provide apiKeyId, inboxId, or both in the body; a request with neither returns 400. Each resource is bound owner-scoped, so you can only bind keys and inboxes that belong to your own account. Returns { "object": "agent_binding", "agentId", "apiKeyId", "inboxId", "bound": true }. Requires the agents:write scope (a key restricted to specific inboxes cannot bind passports: 403), returns 404 when the passport is outside the caller's organization, and records an agent.bound entry in your audit log.

Scope: agents:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl -X POST "https://api.dairo.app/v1/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6/bindings" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Path parameters

Name	Type	Required	Description
`id`	string	yes	Agent UUID or portable agentId (agt_...).

Body

Required, application/json: AgentBindRequest.

Provide an apiKeyId and/or inboxId to bind to this agent.

Field	Type	Required	Description
`apiKeyId`	string or null	no
`inboxId`	string or null	no

Response

200 Success. Body: application/json, AgentBindResponse.

Field	Type	Required
`agentId`	string	yes
`apiKeyId`	string or null	no
`inboxId`	string or null	no
`bound`	boolean	yes

200

{
  "agentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "apiKeyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "inboxId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "bound": true
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`422`	The request is well-formed but a field failed validation (`validation_failed`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).