Connecting User Accounts

Before you can call a user’s GitHub, Slack or HubSpot account, the user has to authorize your app. BundleUp hosts that flow for every provider. You redirect the user to BundleUp, the user approves on the provider’s consent screen, and BundleUp redirects back to you with a one-time code. Your backend exchanges the code for a connection ID. When to use this: whenever a user connects an account in your product, for example from a “Connect GitHub” button in your settings page.

How the flow works

Your app sends the user to BundleUp’s /authorize URL with your client ID, the integration to connect, and where to send them afterwards.
BundleUp checks those values and sends the user to the provider’s consent screen, using your OAuth app.
The user approves. The provider sends them back to BundleUp, which exchanges the provider’s code for tokens, encrypts them and creates a connection.
BundleUp redirects the user to your redirect_uri with a one-time code (or an error).
Your backend exchanges the code for the connection ID, using your API key.

Before you start

An integration for the provider. Note its identifier (for example github).
Your redirect URI registered in the dashboard under Auth → Redirect URIs. It must match exactly, including scheme, host, port, path and trailing slash.
Your client ID, from the same Auth page.
An API key on your backend.

Step 1: Send the user to BundleUp

Build this URL and redirect the user’s browser to it:

https://auth.bundleup.io/authorize
  ?client_id=YOUR_CLIENT_ID
  &integration_id=github
  &redirect_uri=https://app.example.com/callback
  &external_id=user_42
  &state=Rk3jX9...

Parameter	Required	Description
`client_id`	Yes	Your workspace’s client ID.
`integration_id`	Yes	The integration’s identifier, as set in the dashboard (for example `github`).
`redirect_uri`	Yes	Where to send the user afterwards. Must exactly match a registered redirect URI.
`external_id`	No	Your own reference, usually your user ID. Stored on the connection and returned when you exchange the code.
`state`	No	Any value. Returned unchanged on the final redirect, on success and on error. Use it to prevent CSRF.

The SDKs build the URL for you:

const url = client.auth.buildAuthorizationUrl({
  clientId: process.env.BUNDLEUP_CLIENT_ID,
  integrationId: 'github',
  redirectUri: 'https://app.example.com/callback',
  externalId: currentUser.id, // optional
  state, // optional
});

url = client.auth.build_authorization_url(
    client_id=os.environ["BUNDLEUP_CLIENT_ID"],
    integration_id="github",
    redirect_uri="https://app.example.com/callback",
    external_id=current_user.id,  # optional
    state=state,  # optional
)

url = client.auth.build_authorization_url(
  client_id: ENV['BUNDLEUP_CLIENT_ID'],
  integration_id: 'github',
  redirect_uri: 'https://app.example.com/callback',
  external_id: current_user.id, # optional
  state: state # optional
)

Building the URL needs no API key: client_id identifies your workspace but isn’t a secret, and BundleUp only redirects to URIs you registered. Each SDK also exposes the builder as a standalone helper, so you can build the URL in the browser or anywhere the API key must not live: buildAuthorizationUrl from @bundleup/sdk, build_authorization_url from bundleup in Python, and BundleUp.build_authorization_url in Ruby. Exchanging the code afterwards still needs the API key, so keep that step on your server. If the client_id, integration_id or redirect_uri is missing or wrong, BundleUp shows an error page instead of redirecting. Nothing is sent to your redirect URI in that case, because BundleUp can’t trust it.

On the Free plan, users see a BundleUp screen for about a second before they’re sent to the provider. On Pro, they go straight to the provider.

Step 2: The user approves at the provider

The user sees the provider’s consent screen, showing your OAuth app’s name and the scopes configured on the integration. After they approve, the provider sends them back to BundleUp, which completes the token exchange and stores the tokens encrypted. The user has 10 minutes from starting the flow to finish it. After that, they need to start again.

Step 3: Handle the redirect

BundleUp redirects the user to your redirect_uri. On success:

https://app.example.com/callback?state=Rk3jX9...&code=Yx8k2...

Parameter	Description
`code`	One-time code to exchange for the connection. Expires after 5 minutes. Can be used once.
`state`	Your `state`, unchanged. Present only if you sent one.

On failure:

https://app.example.com/callback?state=Rk3jX9...&error=access_denied&error_description=The+user+denied+access

`error`	Meaning
provider’s code	The provider returned an error, passed through as-is. Most commonly `access_denied`: the user clicked Cancel.
`invalid_request`	The provider redirected back without an authorization code.
`token_error`	The provider’s token exchange failed. Often wrong client credentials on the integration.

error_description carries a human-readable explanation. Show the user a friendly message and a way to try again.

Step 4: Exchange the code for a connection ID

From your backend, send the code and the same redirect_uri to BundleUp with your API key:

curl -X POST https://auth.bundleup.io/connection \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "Yx8k2...", "redirect_uri": "https://app.example.com/callback"}'

const { connection_id, external_id, integration_id } =
  await client.auth.getConnectionFromCode({
    code,
    redirectUri: 'https://app.example.com/callback',
  });

connection = client.auth.get_connection_from_code(
    code=code,
    redirect_uri="https://app.example.com/callback",
)
connection_id = connection["connection_id"]

connection = client.auth.get_connection_from_code(
  code: code,
  redirect_uri: 'https://app.example.com/callback'
)
connection_id = connection['connection_id']

200 OK

{
  "connection_id": "conn_abc123",
  "external_id": "user_42",
  "integration_id": "github"
}

integration_id here is the integration’s identifier. external_id is null if you didn’t send one. The exchange fails with 400 if the code has expired, was already used, was issued for a different redirect_uri, or belongs to a different workspace than your API key. A missing or invalid API key returns 401. Full reference: Exchange a code. Store the connection_id against the user. You’re done: use it for every Proxy, Unified API and MCP request for that account.

You also receive a connection.created webhook for every new connection, whether or not you exchange the code. It’s a useful backstop if a user closes the tab before reaching your callback.

Protect the flow with state

Without state, an attacker could trick a signed-in user into completing a flow the attacker started, linking the attacker’s account to the victim’s profile in your app. To prevent that:

Before redirecting, generate a random value and store it in the user’s session.
Pass it as state.
In your callback, compare the state query parameter with the stored value. Reject the request if they differ.

// Before redirecting
const state = crypto.randomUUID();
session.bundleupState = state;

// In the callback
if (req.query.state !== session.bundleupState) {
  return res.status(400).send('Invalid state');
}

Reconnecting an account

Each completed flow creates a new connection, even for the same user and provider. When a user reconnects (for example, to grant new scopes or after revoking access), store the new connection ID and delete the old connection with DELETE /v1/connections/{id}, so you don’t keep unused credentials around.

Why the flow works this way

Your API key never touches the browser. It’s only used in the server-to-server code exchange.
The connection ID never appears in a URL. A leaked callback URL (browser history, server logs, a Referer header) exposes only a code that is short-lived, single-use, bound to your redirect URI, and useless without your API key.
Redirects only go to URIs you registered, so the flow can’t be used to send users somewhere else.

Next steps

Authenticating API requests: use the connection ID.
Connection lifecycle: what happens to a connection after it’s created.

Get started

Concepts

Authentication

Integrations

Proxy

Unified API

MCP

Webhooks

Operations

Platform

Connecting User Accounts

How the flow works

Before you start

Step 1: Send the user to BundleUp

Step 2: The user approves at the provider

Step 3: Handle the redirect

Step 4: Exchange the code for a connection ID

Protect the flow with state

Reconnecting an account

Why the flow works this way

Next steps

​How the flow works

​Before you start

​Step 1: Send the user to BundleUp

​Step 2: The user approves at the provider

​Step 3: Handle the redirect

​Step 4: Exchange the code for a connection ID

​Protect the flow with state

​Reconnecting an account

​Why the flow works this way

​Next steps

How the flow works

Before you start

Step 1: Send the user to BundleUp

Step 2: The user approves at the provider

Step 3: Handle the redirect

Step 4: Exchange the code for a connection ID

Protect the flow with state

Reconnecting an account

Why the flow works this way

Next steps