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

# Core Concepts

> The handful of objects BundleUp is built on, and how they relate to each other.

Four objects explain almost everything in BundleUp: **workspaces**, **integrations**, **connections** and **requests**. API keys and webhooks hang off the workspace.

```mermaid theme={null}
erDiagram
    WORKSPACE ||--o{ INTEGRATION : "configures"
    WORKSPACE ||--o{ API_KEY : "issues"
    WORKSPACE ||--o{ WEBHOOK : "notifies"
    WORKSPACE ||--o{ MEMBER : "has"
    INTEGRATION ||--o{ CONNECTION : "authorizes"
    CONNECTION ||--o{ REQUEST : "makes"
```

A workspace contains integrations, API keys, webhooks and members. Each integration can have many connections, one per connected account. Each connection makes many requests.

## Workspace

The top-level container. Everything else belongs to exactly one workspace, and nothing crosses between workspaces: an API key from one workspace can’t use a connection from another. Use one workspace per environment (development, staging, production). → [Workspaces](/docs/concepts/workspaces)

## Integration

A provider (GitHub, Slack, HubSpot…) configured for your workspace with **your** OAuth app credentials and the scopes you want to request. An integration holds no user data; it’s the template every connection for that provider is created from. → [Integrations](/docs/concepts/integrations)

## Connection

One end user’s authorized account at one provider. It holds the encrypted access and refresh tokens. Its **connection ID** is what you pass on every request to say “act as this account”. → [Connections](/docs/concepts/connections)

## Request

A single call made through the Proxy, Unified API or MCP using a connection. Each one is logged, rate-limited per connection, and counted toward your plan’s usage. → [Requests & usage](/docs/concepts/requests)

## API key and client ID

Two credentials with very different jobs. The **API key** is a secret for your backend; it authorizes requests. The **client ID** is public; it identifies your workspace in the browser when a user starts connecting an account. → [API keys & client ID](/docs/concepts/api-keys)

## Putting it together

A typical lifecycle:

1. You create a **workspace** and add a **GitHub integration** with your GitHub OAuth app.
2. A user clicks “Connect GitHub” in your product. The browser goes to BundleUp with your **client ID**.
3. The user approves. BundleUp creates a **connection** and your backend receives its ID.
4. Your backend makes **requests** with your **API key** and that connection ID.
5. A **webhook** tells your backend when connections are created, refreshed or deleted.

All the terms in one place: [Glossary](/docs/concepts/glossary).


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