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

# Setting Up an Integration

> Register an OAuth app with a provider, then connect it to BundleUp so your users can authorize their accounts.

An [integration](/docs/concepts/integrations) connects BundleUp to one provider using **your own** OAuth app. You set it up once per provider, per workspace. After that, any number of users can connect their accounts through it.

**When to do this:** before the first user connects an account at a new provider, and once in each environment’s workspace.

## How the pieces fit

```mermaid theme={null}
flowchart LR
    subgraph Provider["Provider developer settings"]
        APP["Your OAuth app<br/>client ID + secret<br/>callback: auth.bundleup.io/callback"]
    end
    subgraph BundleUp["BundleUp dashboard"]
        INT["Integration<br/>identifier: github<br/>client ID + secret<br/>scopes"]
        AUTH["Auth settings<br/>your redirect URIs"]
    end
    APP -->|"copy client ID + secret"| INT
    INT -.->|"shows the callback URL to paste"| APP
```

You create an OAuth app at the provider and give it BundleUp’s callback URL. You copy the app’s client ID and secret into a BundleUp integration, along with the scopes you want. Separately, you register your own app’s redirect URI in BundleUp’s Auth settings.

## Step 1: Start the integration in BundleUp

1. In the dashboard, open **Integrations** and add a new one.
2. Pick the provider.
3. Keep the form open. It shows the **Redirect URI** to give the provider:

   ```text theme={null}
   https://auth.bundleup.io/callback
   ```

## Step 2: Create an OAuth app at the provider

In the provider’s developer settings, create an OAuth app (the name varies: “OAuth App”, “App”, “Client”, “Connected App”, “Integration”). Wherever it asks for a **callback URL**, **redirect URL** or **redirect URI**, enter:

```text theme={null}
https://auth.bundleup.io/callback
```

Then copy the app’s **client ID** and **client secret**.

The exact steps differ for every provider. Each provider’s page on [bundleup.io/integrations](https://www.bundleup.io/integrations) links to its developer documentation and notes anything unusual.

<Tip>
  Name the app after your product, not after BundleUp. Users see this name on the consent screen.
</Tip>

## Step 3: Fill in the integration

Back in BundleUp:

| Field | What to enter |
| - | - |
| **Identifier** | A short name you’ll use in code, such as `github`. It must be unique in the workspace. Use the same identifier in every environment. |
| **Client ID** | From your OAuth app. |
| **Client Secret** | From your OAuth app. Stored encrypted. |
| **Scopes** | The permissions to request. Start with the minimum you need. See [Choosing scopes](/docs/guides/integrations/scopes). |
| Provider-specific | Some providers ask for more, such as a subdomain or account region. The form shows what’s needed. |

Save the integration. You receive an `integration.created` [webhook](/docs/guides/webhooks/events).

## Step 4: Register your redirect URI

Open **Auth** in the dashboard and add every URL in your app where users should land after connecting, for example:

```text theme={null}
http://localhost:3000/callback
https://app.example.com/settings/integrations/callback
```

The `redirect_uri` you pass when starting the authorization flow must match one of these **exactly**.

<Note>
  There are two different redirect URLs, and they’re easy to mix up:

  * **BundleUp’s callback** (`https://auth.bundleup.io/callback`) goes in the **provider’s** OAuth app settings. The provider sends users there.
  * **Your redirect URI** goes in BundleUp’s **Auth** settings. BundleUp sends users there.
</Note>

## Step 5: Test it

Open this URL in your browser, with your values filled in:

```text theme={null}
https://auth.bundleup.io/authorize?client_id=YOUR_CLIENT_ID&integration_id=github&redirect_uri=http://localhost:3000/callback
```

You should see the provider’s consent screen with your app’s name. After approving, you’re sent to your redirect URI with a `code`. A new connection appears under **Connections** in the dashboard.

If something goes wrong:

| Symptom | Likely cause |
| - | - |
| BundleUp page says “Invalid client\_id or integration\_id” | Typo in the client ID, or the identifier doesn’t match the integration’s. |
| BundleUp page says “redirect\_uri is not registered” | The `redirect_uri` doesn’t exactly match one under **Auth → Redirect URIs**. |
| The provider shows a redirect or callback URL mismatch | The provider’s OAuth app doesn’t list `https://auth.bundleup.io/callback`. |
| You’re redirected back with `error=token_error` | The client ID or secret on the integration is wrong, or the secret was rotated at the provider. |
| You’re redirected back with `error=access_denied` | You clicked Cancel, or the provider refused the requested scopes. |

More in [Troubleshooting](/docs/guides/operations/troubleshooting).

## Updating and deleting

* **Rotating the client secret:** update it at the provider, then in the integration. Existing connections keep working; their tokens were issued already.
* **Changing scopes:** new connections get the new scopes. Existing connections keep what the user originally approved until the user reconnects.
* **Deleting:** removes the integration **and all its connections**. Their connection IDs stop working immediately.


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