Integrations Overview

Integrations connect a BuilderStudio workspace to an outside provider so nodes and exports can use that provider's credentials. A connection is stored per workspace, scoped to the provider, and the credential material is encrypted at rest. Two kinds of connections exist: OAuth-user connections, where you authorize BuilderStudio against a provider account, and service connections, where you bring your own API key for a supported provider.

How a connection is stored

Each integration connection records the provider, the workspace, a display name, a mode, a status, and an encrypted credential payload. BuilderStudio never stores the raw secret in plaintext: the credential JSON is encrypted before it reaches the database, and saving a connection fails fast if the server's integration encryption key is not configured.

1mode "oauth-user"  -> you authorize BuilderStudio against a provider account2mode "service"     -> you store a provider API key (bring your own key)3 4status: active | pending | error | revoked5 6stored per connection:7- provider8- workspaceId9- displayName10- encrypted credential payload (never plaintext)

API-key (service) connections

Service connections hold a provider API key you supply. They are saved through the provider-connections endpoint, which validates the credential shape for the provider, encrypts it, and upserts the connection on the current workspace.

1POST /api/integrations/provider-connections2 3{4  "workspaceId": "<workspaceId>",5  "provider": "<provider>",6  "displayName": "My provider key",7  "credentialPayload": { /* provider-specific credential fields */ }8}9 10// Include "connectionId" to update an existing connection instead of creating one.

For API-key providers, a per-workspace routing policy decides whether execution prefers your connection or a built-in key. The policy mode is one of:

• auto — use a bring-your-own connection when one exists, otherwise fall back to the built-in key.
• built_in — always use the platform key.
• byo — require your own connection.

OAuth-user connections

OAuth-user connections authorize BuilderStudio against a provider account through a redirect flow rather than a pasted key. The provider returns tokens, BuilderStudio encrypts them, and the connection tracks the granted scopes plus token expiry so it can refresh or surface a re-auth prompt. GitHub and Google Workspace use this style of connection.

Providers available today

The integration surface is intentionally narrow. The currently wired providers are:

Connect a provider

1. 1

   Pick the workspace

   Open the workspace that should own the connection. You need write access on that workspace to add or edit an integration.

2. 2

   Choose API key or OAuth

   For API-key providers, paste the provider credential to create a service connection. For GitHub or Google Workspace, start the OAuth flow and authorize BuilderStudio against your provider account.

3. 3

   Let BuilderStudio encrypt and save

   The credential is validated, encrypted, and upserted on the workspace. A connection that saved successfully shows an active status.

4. 4

   Set the routing policy if needed

   For API-key providers, choose whether the workspace uses your key (byo), the built-in key (built_in), or automatic fallback (auto).