Agent connections
Create AI agent connections in the console — access keys, delivery modes, the webhook signing secret, and delivery history.
An AI agent connection is the credential an agent calls the API with: an access key plus a delivery configuration, scoped to your workspace. Manage connections under AI agents in the console.
Creating a connection
AI agents → New connection asks for:
| Field | Notes |
|---|---|
| Name | Display name for the connection. |
| Access key | The key the agent sends as x-ai-agent-key. You supply the value — generate a long random string. AgentFlow stores only a fingerprint for identification, never the raw key, so it cannot be recovered later. |
| Delivery modes | Polling is always on. Webhook delivery can be enabled here or later. |
| Callback URL | Required for webhook delivery; must be https://. |
If you enable webhook delivery, the console reveals the webhook signing secret exactly once. Store it immediately — the agent (or whoever runs the receiving endpoint) needs it to verify callback signatures, and it cannot be retrieved again.
Hand the access key to the agent integrator through a secure channel — it grants the full agent API for your workspace. See AI agents → Connections for how agents use it.
Managing a connection
Opening a connection shows its identity, delivery configuration, and delivery history:
- Delivery — toggle webhook delivery and edit the callback URL. Enabling webhooks (or updating config when no secret is on record) reveals a new signing secret once.
- Signature verification — rotate the webhook signing secret. Rotation doesn't break in-flight deliveries: each event is signed with the secret that was live when it was queued.
- Connect your agent — ready-made request snippets keyed to this connection, so integrators can copy the wire format directly.
- Deliveries — every webhook delivery attempt: event ID, status
(
pending/delivered/failed), HTTP status, attempts, last error, and callback URL. A failed delivery can be requeued here once the receiver is fixed — see Webhooks → delivery error codes for what the error codes mean.
Deleting a connection disables its key immediately — in-flight agent
calls start failing with unauthorized. Deletion is not recoverable;
create a replacement connection and hand out a new key instead.
Key handling
- Agent keys can't be rotated in place — retire a compromised or lost key by deleting the connection and creating a new one.
- One connection per logical agent keeps delivery history and audit attribution clean.