Step 4 — Add a connection
A connection is one configured integration — GitHub as you, Braintree production, a fal.ai endpoint. It bundles a sealed credential with the actions it exposes, so an agent can act through it without ever seeing the key. (See the four objects.)
Add one
Open Access → Connections and choose Add connection:
- A catalog preset — a ready-made connector for a popular API. Presets that carry Permaura's Verified connector badge have a signed, reviewed manifest, so you know the capability list and endpoints haven't been tampered with.
- An SSH server — run allow-listed commands and move files on a host you own; see Connecting via SSH.
- Coming next — importing your own OpenAPI/GraphQL spec, and generic HTTP connections with an endpoint allowlist. (Both already work over the gateway's REST API if you can't wait.)
Give it a credential
Every connection needs exactly one credential, and you supply it once, at creation. It's sealed on your gateway and never displayed again — you can rotate or replace it, but not read it back.
- API key
- OAuth
API key
Paste the API key, token, or secret the integration issued you. It's encrypted and stored on your gateway; from then on Permaura injects it server-side for each approved call and redacts it from responses.
Best when the integration hands out long-lived keys, or you just want the simplest path.
OAuth
For integrations that issue no API key — Google Workspace, Xero, DocuSign — you connect with your own OAuth app instead. You register one with the provider, hand your gateway its client id and secret, and approve once in a browser. From then on your gateway holds the refresh token and mints access tokens itself, indefinitely.
This is the zero-knowledge path, and it is the only OAuth path Permaura implements today. Your client secret and both tokens are sealed on your gateway. permaura.com is not part of the exchange and never sees any of it.
Requires gateway 1.1.0 or later. The console's Add connection dialog cannot run the flow yet — the OAuth option it shows still reports itself as rolling out. Until it lands, create the connection and authorise it with two calls against your own gateway; each connector's page has the exact commands for that provider.
Two OAuth custody models are specified but not built: a Managed layer where Permaura holds the refresh token for you, and PKCE against a Permaura-registered app. Neither is available, and no plan currently caps OAuth connections.
Choose its capabilities
A connection exposes a list of capabilities — the actions an agent could take through it, like github.pull_requests.create or braintree.transactions.refund. Enable only the ones you want available. A disabled capability can't be used by anyone, regardless of policy.
The kill switch
Every connection has a disable switch. Flip it and every call through that connection is refused instantly, across every agent and grant — no need to unpick individual permissions. Re-enable it just as easily. It's the fastest way to stop something in its tracks.
Adding a connection makes actions possible, not permitted. An agent still can't touch it until a grant allows it — that's the next step.
➡️ Continue to Step 5 — Connect an agent.