Connections First

Breyta guide for setting up reusable connections before wiring flow configuration.

Goal

Create, test, and reuse workspace connections up front so flow setup is faster and less repetitive.

Quick Answer

Use this sequence:

breyta connections list
breyta connections create --type http-api --name "Orders API" --base-url https://api.example.com
breyta connections test <connection-id>
breyta flows configure suggest <slug>
breyta flows configure <slug> --set orders-api.conn=<connection-id>
breyta flows configure check <slug>
breyta flows run <slug> --wait

For human-supplied credentials, open the Breyta setup/connection UI and let the
user enter secrets there. Do not ask for secrets in chat. Protected setup links
should return through /login?redirect=....

LLM connection note:

• Create LLM connections as --type http-api and choose an LLM backend.
• Some UI create surfaces may still show a legacy option like {:type :llm-provider :label "LLM Provider (Legacy)" :description "Legacy create mode normalized to HTTP API with an LLM backend" :icon :sparkles}.
• That legacy create-mode option still normalizes to a canonical :http-api connection. Authored flow requirements and docs should use :http-api.
• For AWS Bedrock Claude, choose the Bedrock backend and AWS SigV4 auth. Use a
  Bedrock Runtime base URL such as
  https://bedrock-runtime.us-east-1.amazonaws.com, set :region to the same
  region, set :service "bedrock", and store access-key-id,
  secret-access-key, plus optional session-token in the referenced secret.

Why This Helps

Canonical Connect-First Workflow

Reuse-First Rules

• Run connections list before every connections create.
• Prefer one stable workspace connection per external system.
• Use clear names (Orders API, Billing DB, Support SMTP) so reuse is obvious.
• Test existing connections before wiring them into new flows.
• When a flow uses connection item dropdowns, inspect connections items before
  assuming a repository, channel, project, or folder is available in setup/run UI.

Missing Connection Handoff

• Declare the :requires slot and provider/auth shape.
• List/reuse/test plausible existing connections.
• If none fits, stop and hand off the setup or connection edit webUrl.
• Resume after the user saves the connection, then test, bind, and run proof.
• For public/end-user flows, model user-owned accounts as :provided-by :installer.

Custom OAuth Accounts

Use a custom OAuth connection when a flow needs a user-authorized http-api account that is not covered by a built-in provider button.

Custom OAuth connections store an OAuth client: your app's client ID and client secret. When a flow is shared, installers reuse the same client to authorize their own accounts. Each installer gets a separate user token and never sees your client secret.

Who can do this:

• Workspace creators/admins can create, edit, and reconnect custom OAuth accounts.

Where to start in the UI:

1. Open Connections.
2. Choose New connection.
3. Choose OAuth account.
4. Choose Use custom OAuth.

You can also start from flow setup when an OAuth-capable slot is unbound:

1. Open flow setup for the slot.
2. Choose Use custom OAuth.
3. Complete the connection form, then finish the browser OAuth redirect.

The setup shape is:

1. Create a pending OAuth account connection.
2. Fill in the provider label, base URL, authorize URL, token URL, probe URL, scopes, and client credentials.
3. Complete the OAuth browser redirect.
4. Test the connection before wiring it into a flow.

Before you start

Gather these values from the provider's OAuth app settings and API docs:

• client ID
• client secret
• authorization endpoint
• token endpoint
• a bearer-authenticated profile or me endpoint for health checks
• required scopes
• whether the provider requires PKCE
• any provider-specific authorize parameters such as audience, resource, access_type, or prompt
• non-standard authorize client ID names or scope separators, configured with :oauth.authorize-params and :oauth.scope-separator
• non-standard token parameter names, configured with :oauth.token-params and :oauth.refresh-token-params

Important client constraint:

• The current custom OAuth form expects a confidential OAuth client with both a client ID and client secret.
• Public-client-only setups are not supported by this form today, even when PKCE is enabled.

Redirect URI to register with the provider

Register this callback URL in the provider's OAuth app configuration:

https://<your-breyta-base-url>/api/oauth/callback

Example:

https://flows.example.com/api/oauth/callback

Notes:

• Replace <your-breyta-base-url> with the base URL where your Breyta UI/API is served.
• Prefer the generic callback URL above for new custom OAuth app registrations.
• Existing custom OAuth apps that already use a workspace-scoped callback can keep working during migration with https://<your-breyta-base-url>/<workspace-id>/api/oauth/callback.

Field Guide

Choosing a Probe URL

The probe URL is used by connections test and other health checks to confirm that the token still works.

Choose an endpoint that:

• accepts the access token as a Bearer token
• returns 200 for a healthy authenticated session
• is lightweight and safe to call repeatedly
• does not mutate provider state

Good examples:

• https://api.x.com/2/users/me
• https://openidconnect.googleapis.com/v1/userinfo
• https://api.github.com/user

Avoid:

• write endpoints
• expensive search/list endpoints
• endpoints that require request bodies or unusual headers beyond normal Bearer auth

PKCE and Extra Authorize Params

Use provider documentation to decide these values:

• Enable PKCE when the provider requires PKCE or documents it as the recommended authorization-code setup.
• Leave Extra authorize params blank unless the provider explicitly requires additional query parameters.

Examples:

{"prompt":"consent"}

{"audience":"https://api.example.com","access_type":"offline"}

Important behaviors:

• Custom OAuth connections are workspace-scoped reusable connections, just like other connection types.
• Changing OAuth endpoints, scopes, or client credentials marks the connection pending and requires reconnect.
• Reconnects preserve the same connection id; flows bound to that connection do not need to be rewired.
• Health checks validate the configured probe/token targets before sending tokens or refresh requests.
• OAuth callback return paths are limited to relative workspace URLs. External return targets are rejected.

Draft Vs Live Wiring

Use breyta flows configure check <slug> for draft and breyta flows configure check <slug> --target live --version latest before the first live release of a new flow.

Common Pitfalls

• Creating a new connection when a matching healthy one already exists.
• Wiring untested connections directly into flows.
• Mixing draft/live config expectations and testing only one target.
• Treating connections test as full runtime proof instead of a preflight check.
• Assuming delete safety from flow code alone; usage guards are profile-binding based (draft/live/installation).

Related

• Flow Configuration
• CLI Workflow
• CLI Commands
• Troubleshooting