Authentication

Each integration offers one or more ways to authenticate. Whichever you choose, the credential is envelope-encrypted at rest and applied server-side when an agent makes a call.

Helios app (OAuth)

The fastest path, available for most OAuth services. Click connect, authorize in the provider's consent screen, and you're done. Helios stores the access and refresh tokens and refreshes them automatically.

Helios apps request broad scopes, so agents can use the full API rather than a slice of it. If that's more than you want to grant, bring your own app.

Bring your own OAuth app

Register an OAuth application with the provider and give Helios its client ID, client secret, and tokens. Use this when you want to:

• request fewer scopes than the Helios app does,
• request more - a beta scope Helios doesn't ask for,
• show your own branding on the consent screen.

Setup is per-provider; each integration's page lists the exact fields it needs.

API key

For services that authenticate with a long-lived key - Stripe, Resend, Apify, Plain, WarpBuild - generate a key in the provider's dashboard and paste it into Helios.

Give the key the narrowest permissions the task requires. A read-only key is the simplest way to guarantee an agent can't mutate anything.

Rotating a key

1. Generate a new key at the provider.
2. Edit the integration in Helios, paste the new key, and save.
3. Revoke the old key at the provider.

Runs already in flight continue with the credential they started with.

Per-user authorization

Some connections need two steps: the workspace or organization installs the app, and then each person authorizes it individually. This is how an agent acts with the right identity rather than a shared one.

This applies to:

• Slack - always.
• GitHub - when the app is installed on an organization or enterprise.

If an agent reports it can't reach one of these services, an unauthorized user is the usual cause.

Who can connect and use an integration

Creating, editing, or deleting an integration requires the editor role on it; using one requires user. Integrations have their own visibility, so you can connect GitHub once at organization visibility and let every project's agents use it.

Sharing an integration never exposes its credential. Users of a shared integration can have agents act through it; they cannot read the token behind it.

See roles and permissions and projects and sharing.

Databases

Database connections authenticate differently - with a connection string, and optionally an SSH tunnel keypair. Both are envelope-encrypted. See databases.