Integrations

An integration (its technical name is an API template) is a configured call to an outside service: a payment processor, an email sender, a CRM, a data feed. Your agent builds it; a workflow invokes it and reads the response.

#What an integration holds

• Where to call: the address, and whether it's a REST or gRPC call.
• What to send: query parameters, headers, and a request body, each worked out at call time from the values the workflow passes in (so one integration serves many cases).
• How to authenticate: none, a bearer token, basic auth, an API key (in a header or a query parameter), or OAuth 1.0a request signing. The credential always comes from a secret; the integration names it and never holds the value.
• A timeout: how long to wait before giving up (raise it for slow services like image generation).

#Your part vs the agent's

The division is the whole point:

• Your agent builds the integration: the address, the shape of the request, which secret it needs.
• You set that secret's value in Dashboard → Secrets. The agent refers to it by name and never sees it.

See Integrations and secrets for the walkthrough, and Secrets for how they're kept.

#OAuth 1.0a: signed requests

Some services, X (Twitter) among them, don't take a token in a header. Each request has to carry a signature computed over its own method, URL and query, using four credentials: a consumer key and consumer secret that identify the application, and an access token and access token secret that identify the account. The first pair rarely changes. The second pair is what you rotate.

An integration with auth type OAuth 1.0a names four secrets, one per credential, and signs every call itself. Nothing in the integration's definition is sensitive, so an agent can build and edit it freely, and the four values live in Secrets where nobody can read them back. To set one up:

1. In the service's developer console, create an app and generate its consumer key and secret, then an access token and access token secret for the account the calls should act as. For X, the app needs read and write permission if it will post.
2. Create four secrets in Dashboard → Secrets and paste one value into each.
3. Have your agent build the integration with those four secret names in its auth block.

A good habit is a second, read-only integration that calls the service's "who am I" route (for X, /2/users/me), so you can check the credentials are wired without doing anything visible.

#How it's used

A workflow's API call step invokes an integration and binds the reply (status, headers, and body) for the rest of that step. The workflow then does something with the result: render it into a page, store it, or pass it to the next step. See Workflows.