> ## Documentation Index
> Fetch the complete documentation index at: https://trytilde.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed connection setup

> Let your application's users connect their own accounts for an agent's tools, without leaving your app.

Users can connect their own accounts, such as Linear or Google, so an agent can act on their behalf with their access. Embedded connection setup shows Tilde's setup page in your app. Tilde hosts the provider's form and OAuth redirects, so credentials never pass through your application.

A connection belongs to the user who made it. The agent sees its tools only in that user's conversations, and only for providers the agent may use personally (the **Use personal tools** capability on the agent's **Capabilities** tab, with the provider selected).

## Server

Mount `@trytilde/embed-server` with the agent listed, as for [chat](https://trytilde.ai/docs/embed/chat.md). The handler serves:

| Request | Does |
| - | - |
| `POST /api/tilde/connections/setup` with `{ provider }` | Starts a setup and returns its page |
| `GET /api/tilde/connections` | Lists the user's connections and their status |
| `POST /api/tilde/connections/<id>/reconnect` | Starts a new setup for an existing connection |
| `DELETE /api/tilde/connections/<id>` | Disconnects it and erases its credentials |

With more than one agent, add `agent` to the body or `?agent=<id>` to the URL.

Your server can do the same directly, for example to send a setup link by email:

```ts theme={"system"}
const setup = await embed.createConnectionSetup({ user: user.id, agent: "<agent id>", provider: "linear" });
// setup.setupUrl expires after ten minutes.
```

## Browser

```ts theme={"system"}
import { connections, mountConnectionSetup } from "@trytilde/embed";

const userConnections = connections({ agent: "<agent id>" });
const setup = await userConnections.setup("linear");

mountConnectionSetup(document.getElementById("connect")!, {
  url: setup.setupUrl,
  connectionId: setup.connectionId,
  onComplete: async () => render(await userConnections.list()),
  onCancel: () => closeDialog(),
});
```

Pass `"popup"` instead of an element to open the page in a popup window. Call it from a click handler so the browser allows it.

In React:

```tsx theme={"system"}
import { ConnectionSetup } from "@trytilde/embed/react";

<ConnectionSetup url={setup.setupUrl} connectionId={setup.connectionId} onComplete={refresh} />;
```

`onComplete` fires when the user finishes and the connection is ready. Statuses are `requires_action` (setup not finished), `ready`, and `failed`. Use `reconnect(id)` for a failed connection and `remove(id)` to disconnect one.


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