# Connecting accounts

A connector returns real data only after the owning organization connects an account for it. Each connector declares how it authenticates; the assistant resolves and decrypts the right credential per call.

## Auth flows

Connectors use one of three flows, declared per service:

<ParamTable rows={[
  { name: "credentials", type: "flow", description: "API key, token, or basic auth pasted into the connect screen. The dominant flow across the catalog." },
  { name: "popup_oauth", type: "flow", description: "OAuth authorization in a popup window — the user approves access and the token is captured automatically." },
  { name: "device_code", type: "flow", description: "Device-code grant: the user confirms the connection on the provider's site using a short code (used by several Yandex services)." },
]} />

The transport — how the secret is attached to each request — is a separate axis (bearer header, basic auth, query token, per-vendor HMAC, and so on) and is handled by the connector itself.

## Where accounts are connected

Accounts are connected in the product UI under organization settings; OAuth-based connectors also surface a connect button inside chat via the `request_form` tool when a call needs an account that isn't connected yet. Programmatically, connection metadata (which fields a connector needs) is available at `GET /api/v1/connectors/metadata`.

## Credential storage

Connected credentials are **encrypted at rest** (Fernet) and stored per user. The assistant never exposes the raw secret; at execution time it resolves and decrypts the credential for the addressed account.

**Multiple accounts (cabinets)**

A single service can hold several connected accounts — multiple Ozon cabinets, two WB sellers. Each is an addressable instance; target one with `instance_id` or a service suffix (`ozon:Top Zip`). See [Calling a connector](/docs/connector-flow#multi-account-addressing).

## Granting connectors and credentials to an agent

An [agent](/docs/agents) is restricted to the connectors and credentials you explicitly grant it. Two layers:

- **Allowed connectors** — `PUT /agents/{id}/connectors` sets which connector keys the agent may call (`wildberries`, `ozon`, …). This decides *what tools* it has.
- **Credential grants** — `POST /agents/{id}/grants` grants a specific connected account to the agent, with optional read/write scopes. This decides *which accounts* it may use.

See the [Agents API](/docs/agents) for the full grant flow.