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 --all
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

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.

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.

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

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>/<workspace-id>/api/oauth/callback

Example:

https://flows.example.com/ws-acme/api/oauth/callback

Notes:

• Replace <your-breyta-base-url> with the base URL where your Breyta UI/API is served.
• Replace <workspace-id> with the workspace where the connection will live.
• The callback URL is workspace-specific, so use the exact workspace id.

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