# connect

> Let a user connect Gmail, Slack, Notion and other apps.

Let a user connect their apps, such as Gmail, Slack and Notion, so Bash can work in them. A connect link signs one user in to one app from the catalog. Once they agree, Bash can use that app in their work.

## TypeScript

```ts
const traveller = vestra.user('traveller-42');

// Get a sign-in link for one app. Send link.url to your user.
const link = await traveller.connect('gmail');
console.log(link.status, link.url);

// Connect an app for your company. Your company's own Bash will use it, so open the link yourself.
const sheets = await vestra.connect('google-sheets');
console.log(sheets.url);

// List their apps. You also get the catalog they may pick from.
const apps = await traveller.connect.list();
const catalog = await vestra.connect.catalog({ search: 'calendar' });
console.log(apps.data.length, catalog.data.length);

// Disconnect an app.
await traveller.connect.remove('con_7hs');
```

## Python

```python
traveller = vestra.user("traveller-42")

# Get a sign-in link for one app. Send link.url to your user.
link = traveller.connect("gmail")
print(link.status, link.url)

# Connect an app for your company. Your company's own Bash will use it, so open the link yourself.
print(vestra.connect("google-sheets").url)

# List their apps. You also get the catalog they may pick from.
apps = traveller.connect.list()
catalog = vestra.connect.catalog(search="calendar")
print(len(apps.data), len(catalog.data))

# Disconnect an app.
traveller.connect.remove("con_7hs")
```

## CLI

```bash
# Get a sign-in link for one app. Send it to your user.
vestra connect gmail --user traveller-42

# List their apps. You can also list every app they may connect.
vestra connect --user traveller-42
vestra connect --catalog --search calendar

# Disconnect an app.
vestra connect --remove con_7hs --user traveller-42
```

## HTTP

```bash
# Get a sign-in link for one app. It is for one user: send them its url.
curl "$VESTRA_BASE_URL/v1/connections" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "traveller-42", "app": "gmail" }'

# List their apps. You can also list the catalog your users may pick from.
curl "$VESTRA_BASE_URL/v1/connections?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

curl "$VESTRA_BASE_URL/v1/apps?search=calendar" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# Disconnect an app. user_id says whose connection it is.
curl -X DELETE "$VESTRA_BASE_URL/v1/connections/con_7hs?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"
```

## MCP

```json
{
  "method": "tools/call",
  "params": {
    "name": "connect",
    "arguments": { "user": "traveller-42", "app": "gmail" }
  }
}
```

## Good to know

### When Bash needs an app during a job

If Bash needs an app during a job, it sends an interaction of type `connect`: a request that waits for an answer. Send your user its link, or answer `{ approve: false }` to decline.

### After the user agrees

Once your user agrees, they are sent to your `return_url`, or to your company's first allowed return URL. Your webhooks receive `connection.completed` or `connection.failed`, so you know how it went.

### Which apps users can connect

`GET /v1/apps` lists the apps your users may connect, with your company's allowlist applied.

## The routes behind connect

- `GET` [/v1/apps](https://vestra.ai/developers/reference/api/connected-apps/get-v1-apps.md): The apps your users may connect, after your allowlist. Key scope: `runtime` (or `all`).
- `POST` [/v1/connections](https://vestra.ai/developers/reference/api/connected-apps/post-v1-connections.md): Get a connect link for one app, for one user (user_id) or the company's own Bash. After consent the user lands on your return_url (or your first allowed one, or our own page), and a webhook fires. The link carries the id of the connection it makes. Key scope: `runtime` (or `all`).
- `GET` [/v1/connections](https://vestra.ai/developers/reference/api/connected-apps/get-v1-connections.md): The connected apps of one user (user_id), or of the company's own Bash. Key scope: `runtime` (or `all`).
- `GET` [/v1/connections/{connection_id}](https://vestra.ai/developers/reference/api/connected-apps/get-v1-connections-connection-id.md): One connection's status. user_id names whose it is. Key scope: `runtime` (or `all`).
- `DELETE` [/v1/connections/{connection_id}](https://vestra.ai/developers/reference/api/connected-apps/delete-v1-connections-connection-id.md): Disconnect. user_id names whose it is. Key scope: `runtime` (or `all`).
- `GET` [/v1/connect/return](https://vestra.ai/developers/reference/api/connected-apps/get-v1-connect-return.md): Hosted by us. The app sends the user here after consent; we record it and forward them to your return_url. You never call it.

Next: [`memory`](https://vestra.ai/developers/memory.md)