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:
| Field | Type | Description |
|---|---|---|
| credentials | flow | API key, token, or basic auth pasted into the connect screen. The dominant flow across the catalog. |
| popup_oauth | flow | OAuth authorization in a popup window — the user approves access and the token is captured automatically. |
| device_code | flow | 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.
Granting connectors and credentials to an agent
An agent is restricted to the connectors and credentials you explicitly grant it. Two layers:
- Allowed connectors —
PUT /agents/{id}/connectorssets which connector keys the agent may call (wildberries,ozon, …). This decides what tools it has. - Credential grants —
POST /agents/{id}/grantsgrants a specific connected account to the agent, with optional read/write scopes. This decides which accounts it may use.
See the Agents API for the full grant flow.