# Integrations

Connect your app to external services — anything that uses OAuth, API keys, or bearer tokens. Foundation runs the auth flow and stores the tokens; your app just manages connections and calls the capabilities you expose.

This page has two halves: **Configure** sets integrations up on the platform (no code), and **Use in your app** wires connection management into the frontend you're building.

## Configure

Set integrations up on the platform side — in the dashboard or by asking your agent. No code required.

### Connect a service

Add an integration and Foundation handles the auth flow end to end: OAuth redirects, token storage, and refresh tokens. You don't see or store secrets in your app.

### Map capabilities

Each integration exposes capabilities — the methods you can call on the external service. A Google Calendar integration might expose:

- List events
- Create event
- Update event
- Delete event

### Choose how capabilities are exposed

- **REST API** — your app's users call integration methods through your API
- **MCP** — AI agents use your integrations as tools
- **AI Prompts** — wire integrations into your prompt chains as tools

### Control access

Integration access is governed by [roles and scopes](/platform/roles). You decide which users and which external agents can use which integrations.

## Use in your app

The SDK manages **connections** — listing the catalog, connecting, checking status, disconnecting. Invoking an integration's capabilities (list events, etc.) happens through the surface you exposed in Configure (your REST API or MCP), not a direct SDK call. Full method signatures live in the [SDK reference](/api/sdk).

### Show the catalog and connection state

```ts
const integrations = await foundation.integration.all()  // catalog + current connection state
```

Use `all()` rather than stitching `list()` and `connections()` yourself.

### Connect a service

```ts
const result = await foundation.integration.connect(source)

if (result.url) {
  // open a popup or redirect, then refresh connection status when it returns
  window.open(result.url, 'connect', 'width=600,height=700')
}
// also handle immediate success / configuration responses
```

### Disconnect

```ts
// only after explicit user confirmation
await foundation.integration.disconnect(source, configurationId)
```

### Drop-in connect button (optional)

If you don't want to build the connect UI, use the web component:

```ts
import 'foundation-sdk/components'
;(window as any).__foundation = foundation
```

```html
<foundation-connect integration-id="github-oauth"></foundation-connect>
```

It emits `success`, `error`, and `close` events. In Vue, configure `isCustomElement` for `foundation-*` tags.

## Reference

- SDK methods used here: `foundation.integration.all()`, `.connect()`, `.disconnect()`, `.status()`, `.connections()` — see the [SDK reference](/api/sdk)
- [Roles & Scopes](/platform/roles) for per-integration access control
- [MCP & API Overview](/api/overview) for exposing capabilities as tools