Skip to main content
A connection is created every time a user completes the authorization flow. It represents one account, at one provider, authorized by one user, through one integration. A connection holds:

​
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:
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:
You get it back when you exchange the code, in webhook payloads (externalId), and you can filter by it with the Platform API:
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}.
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.

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

​
Managing connections

The full reference is under Platform API.