Assign Connections to an agent

Assign one Connection — or every Connection a ConnectionVault names at this moment, never a standing subscription — to one Agent by minting ordinary use_connection PermissionAssignments (subject agent_definition). An optional D194 window (valid_from/expires_at) and rationale ride onto every minted PermissionAssignment unchanged. Bounds require canonical UTC timestamps with exactly three fractional digits. A request whose authority window already exists adopts that PermissionAssignment rather than duplicating it, and returns its id; because bounds are part of PermissionAssignment identity, assigning a window beside an existing unbounded PermissionAssignment adds a second row rather than narrowing the first — unassign the unbounded one to time-box the access. An archived vault is refused. Returns the assigned edges, each naming its exact PermissionAssignment id. No new enforcement exists behind this verb: the CapabilityGateway keeps consulting PermissionAssignments exactly as before, and deleting a minted PermissionAssignment is a complete unassign. Requires an Idempotency-Key.

Checkfu support posture: alpha; hosted. Required evidence journey: connection-lifecycle. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

POST /v1/agents/{agent_id}/assigned-connections

Assign Connections to an agent

cURL

curl --request POST \
  --url https://api.checkfu.com/v1/agents/{agent_id}/assigned-connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "target": {
    "kind": "connection",
    "connection": "<string>"
  },
  "expires_at": "<string>",
  "valid_from": "<string>",
  "rationale": "<string>"
}
'

201

{
  "agent_id": "<string>",
  "assigned": [
    {
      "connection_id": "<string>",
      "permission_assignment_id": "<string>",
      "expires_at": "<string>",
      "valid_from": "<string>"
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version · enum<string> · required

Available options: 2026-08-27

idempotency-key · string · required

Required string length: 1 - 255

Path Parameters

agent_id · string · required

Pattern: ^agent_[0-9a-f]{32}$

Body

application/json

target · object · required

Option 1

Option 2

Show child attributes

expires_at · string

A retained audit timestamp using the historical zero-to-three fractional-digit encoding.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$

valid_from · string

A retained audit timestamp using the historical zero-to-three fractional-digit encoding.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$

rationale · string

Required string length: 1 - 512

Response

201

application/json

Success

agent_id · string · required

Pattern: ^agent_[0-9a-f]{32}$

assigned · object[] · required

Show child attributes