Connections

An AI agent connection binds an API key, a workspace, and a delivery configuration. Operators create and manage connections in the console; agents use the resulting key to call the agent API.

Creating a connectionCopy Anchor Link

Connections are created by an operator in the console under AI agents → New connection:

• Name — display name for the connection.
• Access key — the key your agent will send as x-ai-agent-key. You supply the value (generate a long random string); AgentFlow does not generate it.
• Callback URL — required when webhook delivery is enabled. Must be https://; any other scheme is rejected.
• Delivery modes — polling is always on; webhook delivery can be toggled per connection.

If webhook delivery is enabled, the console shows a webhook signing secret exactly once — it is never retrievable afterward. Store it immediately; you need it to verify callback signatures. To get a new secret, rotate it from the connection page — events already in flight still verify against the secret that was live when they were sent.

The full console walkthrough is in Using the platform → Agent connections.

Authenticating as an agentCopy Anchor Link

Every ai-agent procedure takes the access key in the x-ai-agent-key header:

curl -s https://af-api.ivalt.com/api/v1/ai-agent/getIdentity \
  -H 'x-ai-agent-key: <agent-key>' \
  -H 'content-type: application/json' \
  -d '{"json": {}}'

An absent or unknown key fails with 401 unauthorized and data.reason: "ai_agent_access_key_required". The raw key is never stored and cannot be recovered — if it is lost, create a new connection.

getIdentityCopy Anchor Link

getIdentity returns the authenticated connection's identity and its effective delivery configuration:

{
  "json": {
    "id": "pc_a1b2c3d4e5f6",
    "tenantId": "org_example",
    "name": "Correspondence Agent",
    "deliveryConfig": {
      "polling": true,
      "webhook": true
    }
  }
}

Call it at startup (and when configuring a webhook receiver) to learn which delivery modes apply to your requests:

• polling: true — always; getStatus + getProof work for every request.
• webhook: true — the connection can receive approval.completed callbacks (it still needs a callback URL set).

Key handlingCopy Anchor Link

• Store the key in your secret manager; it cannot be retrieved or rotated in place. Keys that appear in logs or source control should be retired by creating a replacement connection.
• The key grants every ai-agent procedure for one workspace. There are no finer-grained scopes today.