A connection is your workspace’s link to an outside service: Stripe, Shopify, or any service with an OpenAPI document or a GraphQL schema. Its operations become tools; your agent calls them through aeria, and neither your client nor a sandbox ever holds the service’s key.

Set one up

1. Your agent calls connection_ask {service} (a service of aeria’s catalog), or connection_ask {spec} for any other.
2. aeria answers a link, app.aeria.dev/connect/<token>: yours alone, 15 minutes, used once.
3. You open it, signed in: the service, its hosts, where to find its key, its fields.
4. You type the values. Each secret is sealed in your browser before it leaves it; aeria receives the plain fields and the sealed values only.

A refusal gives the link back. A secret’s value is never sent in clear, never repeated in a refusal, never in an event.

Its operations as tools

Once set, each operation of the service is a tool:

• Named <connection>_<operation>: the operation’s id in snake case (stripe_get_balance); a GraphQL query’s or mutation’s field the same (shopify_products).
• Found with tool_search {keyword}, each with its level. A connection whose document could not be read is listed as unavailable, with why.
• At deny until you expose it: tool_level_set {tool, level}.
• Called with tool_call {tool, params}: aeria builds the request, the egress adds the connection’s headers and sends it, the service’s JSON is answered. Each call is an event, its secrets masked.

They are never in your client’s tool list: a client keeps the list it got as it connected, and Stripe’s operations alone are 612.

Where the key goes

A connection’s secret is opened in one place only: your workspace’s egress, a Worker that holds your workspace’s key. It adds the secret to the request’s headers toward the connection’s own hosts, and nowhere else (host_refused). A preview never opens a connection (preview). In the service’s answer, any secret it sent back is replaced by its placeholder.

A spec

A service of the catalog has its spec already; for another, your agent writes one in YAML:

label: Stripe
help: https://dashboard.stripe.com/apikeys
fields:
  secret_key: {label: Secret key, secret: true, pattern: "^(sk|rk)_"}
  account: {label: Connected account, optional: true}
hosts: [api.stripe.com]
headers:
  - {name: Authorization, format: "Bearer {secret_key}"}
  - {name: Stripe-Account, format: "{account}"}
openapi: {url: "<the pinned document>", digest: "<its sha256>"}

label     the service's name (required)
help      where its key is made
fields    name: {label, secret, pattern, variable, optional}
hosts     its hosts, one at least
token     {url, form}: a token exchange the egress runs
headers   [{name, format}], from {field} or {token}
openapi   {url, digest}: the document, pinned by its sha256
graphql   {url}: the endpoint, read by introspection

A part that does not read is refused invalid. A host on aeria.run, where agent-written code runs, is refused app_host.

Its name

Lower-case letters, digits and single dashes, starting with a letter, 31 characters at most; not one of aeria’s tools’ first words, not an app’s (taken).

An app is a connection too

Every app is a connection of its workspace, named as the app: its operations read from its production’s /openapi.json, its one secret the app’s own key, made by aeria. It is archived with its app.

Its tools

connection_ask, connection_search, connection_show, connection_archive, tool_search, tool_call; connection_set is the setup page’s only. Each with its level: Tools.

Archived, a connection’s tools and secrets are no longer used; its record is kept, and its name is free again.