External services

Most processes do not stay inside Perstack. They read email, post to chat, look something up over an existing API, or write to a system your organization already runs. Connecting those services is what lets a definition's operations reach them.

What you connect

A connection is how a Project Environment reaches a service it needs to sign in to. Connections come from a catalog of presets — the services Perstack knows how to authorize against — and are created through an OAuth flow: you pick a preset and go through that service's own sign-in and consent screen, and Perstack stores the resulting tokens rather than a password or a static key you hand it directly. A connection belongs to the Environment and its selected immutable version is included in each configuration revision that uses it. See the API reference for the preset catalog and the connections it produces.

A connection is not the only way to reach an external system. A service that authenticates with a key or a token rather than an OAuth sign-in is reached with a stored value instead, held by the platform the same way and supplied to the call rather than to the agent. Provider settings are separate: when an Environment has no selected provider setting, the platform default is used; Studio does not require a dummy setting to enable that default.

Once a connection exists, an operation in a definition can reference it by name. Describing a process that says "send a message to the customer" or "look up the account in the billing system" is enough — the definition wires that step to the connection you set up, and you do not repeat the credential setup per operation.

Where credentials live

Credentials for a connected service are held by the platform, not by the agent. An agent calling an operation that reaches an external service does not see the API key, the OAuth token, or the account password behind it — it asks for the operation, and the platform performs the call.

This is the same separation that governs operations generally: the agent has access to what an operation lets it do, not to the mechanism underneath it. See Operations and rules.

The gateway

Every call to an external service goes through a gateway rather than being made directly by the agent. The gateway is what actually holds the credential, makes the request, and returns the result. This means a call to an external service is visible the same way any other operation is: it shows up on the run's record, with what was sent and what came back, described in Reading the record.

It also means revoking or rotating a credential is a change in one place — the connection or provider credential version — rather than something that has to be found and updated everywhere an agent might have referenced it. A later configuration revision must pin the replacement explicitly; an existing snapshot does not silently move to the latest credential.

To manage programmatic access to Perstack itself, rather than the services it connects to, see API keys. For the reverse direction — events leaving Perstack for your own systems — see Webhooks.