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

# connections

> Third-party account auth for a persona — client.connections.

Connections give a persona an authorized account on an external tool. Nine methods across three levels: the **catalogue** (which apps exist), the org-level **auth config** (how one of them authenticates) and the identity-level **connection** (one authorized account). API detail: [Connections](/docs/api/connections).

**There is no list of supported apps.** `connector` is an app id out of the catalogue, so a setup starts with a search:

```ts theme={"system"}
import { CONNECTION_AUTHS } from "@usenaive-sdk/vetta";
// CONNECTION_AUTHS: ["managed_oauth", "oauth", "api_key"]

const { data } = await client.connections.listApps({ search: "helpdesk" });
const app = await client.connections.getApp(data[0].slug);
const config = await client.connections.createAuthConfig({ connector: app.slug });
const conn = await client.connections.connect({
  auth_config_id: config.id,
  identity: "idn_...",
  fields: { subdomain: "acme" },       // app.connect_fields says whether any are needed
});
conn.connect_link;                      // hand this to the person who owns the account
```

## listApps

```ts theme={"system"}
client.connections.listApps(query?: { search?: string; limit?: number; after?: string }): Promise<Page<ConnectionApp>>
```

`GET /v1/connections/apps`. Searches the catalogue by name, id or description. Each row carries the `slug` that `connector` takes and an `auth` array saying which setup paths work — `managed_oauth` needs no credentials of your own. `next_cursor` is opaque, not a row id.

## getApp

```ts theme={"system"}
client.connections.getApp(slug: string): Promise<ConnectionAppDetail>
```

`GET /v1/connections/apps/{slug}`. Adds `default_tools` (the operations pinned when you name none) and `connect_fields` (what `connect` will still be asked for). `not_found` for an id the catalogue does not know — this is what replaced the old connector enum.

## createAuthConfig

```ts theme={"system"}
client.connections.createAuthConfig(body: AuthConfigCreate): Promise<AuthConfig>
```

`POST /v1/connections/auth_configs`. `AuthConfigCreate` is `{ connector, auth?, scopes?, tools?, client_id? }`, where `connector` is an app `slug`. `tools` pins the callable operations — omitted, the app's `default_tools` are pinned, and anything outside the pin is refused at the provider. Org-level and shared across every identity that connects that app.

## listAuthConfigs

```ts theme={"system"}
client.connections.listAuthConfigs(): Promise<Page<AuthConfig>>
```

`GET /v1/connections/auth_configs`.

## deleteAuthConfig

```ts theme={"system"}
client.connections.deleteAuthConfig(id: string): Promise<Deleted>
```

`DELETE /v1/connections/auth_configs/{id}`.

## connect

```ts theme={"system"}
client.connections.connect(body: { auth_config_id: string; identity: string; fields?: Record<string, string> }): Promise<Connection>
```

`POST /v1/connections`. Mints a connected account and its Connect Link; the account starts `initiated` with a `connect_link` to hand to the person who authorizes it. `fields` carries the config's `connect_fields` — omitted, the hosted page asks the person instead. Requires `billing:write` — a managed account is a per-account charge at the provider.

## list

```ts theme={"system"}
client.connections.list(query?: { identity?: string }): Promise<Page<Connection>>
```

`GET /v1/connections`, optionally filtered to one persona.

## get

```ts theme={"system"}
client.connections.get(id: string): Promise<Connection>
```

`GET /v1/connections/{id}`. **This read is the refresh** — status is reconciled against the provider before answering. States: `initiated → active | failed`, and `disconnected` once revoked; `connect_link` is present only while `initiated`. There is no `connection.*` webhook yet, so polling this is how you learn that a person finished authorizing.

## disconnect

```ts theme={"system"}
client.connections.disconnect(id: string): Promise<Deleted>
```

`DELETE /v1/connections/{id}`. Revoke: the provider drops the stored credential and every later call through the connection is refused.