> ## Documentation Index
> Fetch the complete documentation index at: https://bundleup.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How BundleUp Works

> The parts of BundleUp, where they run, and what happens to a single request from your backend to a provider and back.

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

```mermaid theme={null}
flowchart TB
    subgraph You[Your product]
        FE[Your frontend]
        BE[Your backend]
    end

    subgraph BU[BundleUp]
        AUTH["auth.bundleup.io<br/>Authorization flow"]
        API["api.bundleup.io<br/>Platform API"]
        subgraph EDGE[Edge, global]
            PROXY["proxy.bundleup.io"]
            UNIFY["unify.bundleup.io"]
            MCP["mcp.bundleup.io"]
        end
        STORE[("Encrypted<br/>credentials")]
        JOBS["Background jobs<br/>webhooks, usage, log retention"]
    end

    PROV[Provider APIs]

    FE -->|"redirect: client_id"| AUTH
    BE -->|"API key"| API
    BE -->|"API key + connection ID"| EDGE
    AUTH --> STORE
    EDGE --> STORE
    EDGE --> PROV
    JOBS -->|"signed POST"| BE
```

| Host | What it does | Who calls it |
| - | - | - |
| `auth.bundleup.io` | Runs the [authorization flow](/docs/guides/auth/authorization-flow) and exchanges one-time codes for connection IDs. | Your user’s browser, your backend |
| `api.bundleup.io` | The [Platform API](/docs/api-reference/introduction): manage connections, integrations and webhooks. | Your backend |
| `proxy.bundleup.io` | The [Proxy](/docs/guides/proxy/overview): forwards any request to the provider’s API. | Your backend |
| `unify.bundleup.io` | The [Unified API](/docs/guides/unified/overview): normalized endpoints per category. | Your backend |
| `mcp.bundleup.io` | [MCP](/docs/guides/mcp/overview): forwards MCP traffic to the provider’s own MCP server. | Your backend, or an AI model provider |

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](/docs/guides/webhooks/overview) 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](/docs/guides/auth/authorization-flow).

## What happens to a request

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

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant B as Your backend
    participant E as BundleUp edge
    participant P as Provider

    B->>E: Request + Authorization: Bearer API key + BU-Connection-Id
    E->>E: Validate API key → workspace
    E->>E: Load connection (must belong to that workspace)
    E->>E: Check rate limit (100 / 60s per connection)
    alt Token expires within 60 seconds
        E->>P: Refresh token
        P-->>E: New token
    end
    E->>E: Decrypt token in memory
    E->>P: Forward request with the user's token
    P-->>E: Response
    E-->>B: Response (streamed back)
    E-)E: Write request log (asynchronously)
```

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](/docs/guides/proxy/retries).
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

<Columns cols={2}>
  <Card title="Proxy vs Unified API vs MCP" icon="signs-post" href="/docs/choosing-a-surface">
    Pick the right way to call a connected account.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/docs/quickstart">
    Connect an account and make your first request.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.