> ## 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.

# Proxy Overview

> Call any provider’s own API as a connected user, with authentication, token refresh, retries, rate limiting and logging handled for you.

The Proxy lets you call a provider’s API exactly as its documentation describes, as if you were calling it directly. You change the base URL to `https://proxy.bundleup.io` and add two headers. BundleUp attaches the user’s access token, refreshes it when needed, retries safe requests that fail, and logs the call.

```bash theme={null}
# Calling GitHub directly
curl https://api.github.com/user/repos \
  -H "Authorization: Bearer <the user's GitHub token>"

# The same call through BundleUp
curl https://proxy.bundleup.io/user/repos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "BU-Connection-Id: conn_abc123"
```

## When to use the Proxy

* You need a provider-specific endpoint, field or feature.
* You’re **writing** data (creating issues, sending messages, updating records) beyond what the [Unified API](/docs/guides/unified/overview) offers.
* You already have code against a provider’s API and want to stop managing tokens.
* You integrate deeply with one or two providers and don’t need a shared data shape.

If you want the same request to work across many providers in a category, look at the [Unified API](/docs/guides/unified/overview) first. See [Proxy vs Unified API vs MCP](/docs/choosing-a-surface).

## How it works

```mermaid theme={null}
sequenceDiagram
    participant B as Your backend
    participant X as proxy.bundleup.io
    participant P as Provider API

    B->>X: GET /user/repos<br/>Authorization: Bearer API key<br/>BU-Connection-Id: conn_abc123
    X->>X: Authenticate, resolve connection,<br/>rate limit, refresh token if needed
    X->>P: GET https://api.github.com/user/repos<br/>Authorization: Bearer user's token
    P-->>X: 200 OK + body
    X-->>B: 200 OK + body, unchanged
```

BundleUp takes the path and query string of your request, puts them on the provider’s base URL (which it knows from the connection’s integration), swaps your `Authorization` header for the user’s token, and sends it. The provider’s response comes back to you as-is.

## What the Proxy does

* **Routes** to the right provider based on the connection, not the URL. The same path on two connections can go to two different providers.
* **Authenticates** with the user’s access token, refreshing it first if it’s expired or about to expire.
* **Retries** `GET`, `HEAD` and `OPTIONS` requests on timeouts, `429`, `502`, `503` and `504`. See [Retries](/docs/guides/proxy/retries).
* **Rate-limits** each connection to 100 requests per 60 seconds. See [Rate limits](/docs/guides/proxy/rate-limits).
* **Times out** a provider call after 20 seconds (10 seconds for each retry).
* **Logs** every call with status and duration. See [Logs](/docs/guides/operations/logs).

## What the Proxy doesn’t do

* **It doesn’t change the response.** Status, headers and body are the provider’s. Provider errors reach you unchanged, so you handle them exactly as the provider documents.
* **It doesn’t validate your request.** Paths, query parameters and bodies go to the provider as you sent them.
* **It doesn’t store bodies.** Neither requests nor responses are logged.

## Next steps

<Columns cols={2}>
  <Card title="Making requests" icon="paper-plane" href="/docs/guides/proxy/making-requests">
    Methods, headers, bodies, GraphQL and binary data.
  </Card>

  <Card title="Retries" icon="rotate" href="/docs/guides/proxy/retries">
    Which requests are retried, and how to change it.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/docs/guides/proxy/rate-limits">
    The per-connection limit and how to handle 429s.
  </Card>

  <Card title="Proxy reference" icon="book" href="/docs/api-reference/proxy">
    The endpoint, headers and errors.
  </Card>
</Columns>


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