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

# Connections

> A connection is one end user’s authorized account at one provider. Its ID is what you pass on every request.

A **connection** is created every time a user completes the [authorization flow](/docs/guides/auth/authorization-flow). It represents one account, at one provider, authorized by one user, through one [integration](/docs/concepts/integrations).

A connection holds:

| Field | What it is |
| - | - |
| `id` | The **connection ID**. Pass it in the `BU-Connection-Id` header to act as this account. |
| `integration_id` | The integration the connection was created through. |
| `external_id` | Your own reference, usually your user or tenant ID. Optional. You set it when starting the flow, or later. |
| Access token | Encrypted. Used by BundleUp to call the provider. Never sent to the browser. |
| Refresh token | Encrypted. Used by BundleUp to get a new access token when the current one expires. |
| `expires_at` | When the current access token expires, if the provider says so. |
| `created_at`, `updated_at` | When the connection was created and last changed. |
| Last refreshed | When BundleUp last refreshed the access token. Shown in the dashboard and as `refreshedAt` in webhook payloads. |

## The connection ID

The connection ID is the only thing your application needs to keep. Store it in your database next to the user or account it belongs to:

```sql theme={null}
-- example
ALTER TABLE users ADD COLUMN github_connection_id TEXT;
```

It stays the same for the life of the connection, including across token refreshes. You don’t need to re-authorize the user unless the connection is deleted, or the user revokes access at the provider.

The connection ID on its own grants nothing. Every request also needs your workspace’s API key, and the connection must belong to the same workspace as the key.

## External ID

`external_id` is a free-form string you attach to a connection to link it back to your own records. Set it when you build the authorization URL:

```text theme={null}
https://auth.bundleup.io/authorize?...&external_id=user_42
```

You get it back when you exchange the code, in webhook payloads (`externalId`), and you can filter by it with the Platform API:

```bash theme={null}
curl "https://api.bundleup.io/v1/connections?external_id=user_42" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This is useful when you need to find a user’s connections without storing the connection ID yourself, or to reconcile after a missed webhook. You can change it later from the dashboard or with `PATCH /v1/connections/{id}`.

<Note>
  External IDs aren’t unique. If the same user connects the same provider twice, you get two connections with the same `external_id`. Each run of the authorization flow creates a new connection.
</Note>

## How tokens stay valid

You don’t refresh tokens yourself. When a request arrives and the connection’s access token has expired or will expire within 60 seconds, BundleUp refreshes it before forwarding the request. If the token is merely due for an early refresh, BundleUp refreshes it in the background and uses the current token for this request.

Details, including what happens when a refresh fails: [Connection lifecycle](/docs/guides/auth/connection-lifecycle).

## Managing connections

| Task | Dashboard (**Connections**) | Platform API |
| - | - | - |
| List and filter | Yes | `GET /v1/connections` |
| View one | Yes | `GET /v1/connections/{id}` |
| Change the external ID | **Update connection** | `PATCH /v1/connections/{id}` |
| Refresh the token now | **Refresh connection token** | — |
| Delete (and revoke at the provider, where supported) | **Delete connection** | `DELETE /v1/connections/{id}` |
| Import existing tokens | — | `POST /v1/connections` |

The full reference is under [Platform API](/docs/api-reference/introduction).


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