How BundleUp Works

BundleUp has two jobs. First, it connects your users’ accounts: it runs the OAuth flow and stores the resulting tokens. Second, it executes requests against those accounts: your backend sends a request with an API key and a connection ID, and BundleUp forwards it to the provider with the right token.

​

The parts

The Proxy, Unified API and MCP run on a globally distributed edge network, so a request is handled close to where it starts, with no central region to route through. Background jobs deliver webhooks to your backend, aggregate usage for billing, and delete request logs once they pass your plan’s retention window.

​

Connecting an account

Before you can make requests, a user has to connect an account. This happens once per account:

1. Your frontend sends the user to auth.bundleup.io with your client ID and the integration to connect.
2. BundleUp sends the user to the provider’s consent screen, using your OAuth app.
3. The provider redirects back to BundleUp with an authorization code. BundleUp exchanges it for tokens, encrypts them, and creates a connection.
4. BundleUp redirects the user back to your app with a one-time code.
5. Your backend exchanges that code for the connection_id using your API key, and stores it.

The full flow, with a sequence diagram, is in Connecting user accounts.

​

What happens to a request

Every request to the Proxy, Unified API or MCP goes through the same steps before it reaches the provider:

1. Authenticate. The API key is hashed and looked up. An unknown key is rejected with 401.
2. Resolve the connection. The connection ID must exist and belong to the same workspace as the API key. If it doesn’t, the request is rejected with 400 connection_invalid (404 on the Unified API).
3. Rate limit. Each connection can make 100 requests per 60 seconds. Over that, the request is rejected with 429 and nothing is sent to the provider.
4. Make sure the token is usable. If the access token has expired, or will expire within 60 seconds, it is refreshed before the request continues. If it is only due for a refresh, the refresh runs in the background and the current token is used, so the request doesn’t wait.
5. Decrypt. The token is decrypted in memory for this request only.
6. Forward. The request goes to the provider with the user’s token in the Authorization header. On the Proxy and Unified API, failed idempotent requests are retried.
7. Respond and log. The provider’s response is returned to you. The log entry (status, duration, connection, URL) is written after the response, so logging adds no latency.

Steps 1 to 3 happen before anything reaches the provider. A request rejected there never touches the user’s account.

​

What BundleUp doesn’t do

• It doesn’t store request or response bodies. Logs record metadata only.
• It doesn’t change the provider’s response on the Proxy or MCP. You get exactly what the provider returned. The Unified API reshapes successful responses into its normalized format, and passes errors through unchanged.
• It doesn’t queue or schedule your requests. Each call is executed when you make it.

​

Next steps