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. The grant is two layers — what tools it has, and which accounts it may use:
Allow connectors
PUT /agents/{id}/connectors sets which connector keys the agent may call (wildberries, ozon, …). This decides what tools it has. A connector the agent isn't allowed simply isn't in its toolset.
Grant a credential
POST /agents/{id}/grants grants a specific connected account to the agent, with optional read/write scopes. This decides which accounts it may use — an allowed connector with no granted account still can't return data.
The agent calls under its grants
At execution time the agent can only reach the connectors it was allowed and the accounts it was granted; everything else is out of scope. Revoke by removing the grant.
See the Agents API for the full grant flow.
FAQ
What auth flows do connectors use?
One of three, declared per service — credentials (API key, token or basic auth), popup_oauth (OAuth in a popup), and device_code (confirm on the provider's site with a short code). The transport that attaches the secret to each request is a separate axis handled by the connector.
How are credentials stored?
Connected credentials are encrypted at rest with 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.
Can one service hold more than one account?
Yes. 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 such as ozon:Top Zip.
How does an agent get access to a connector and its credentials?
In two layers. PUT /agents/{id}/connectors sets which connector keys the agent may call (what tools it has). POST /agents/{id}/grants grants a specific connected account with optional read/write scopes (which accounts it may use). An agent can only reach what you explicitly grant.
Frequently asked questions
What auth flows do connectors use?
One of three, declared per service — credentials (API key, token or basic auth), popup_oauth (OAuth in a popup), and device_code (confirm on the provider's site with a short code). The transport that attaches the secret to each request is a separate axis handled by the connector.
How are credentials stored?
Connected credentials are encrypted at rest with 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.
Can one service hold more than one account?
Yes. 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 such as ozon:Top Zip.
How does an agent get access to a connector and its credentials?
In two layers. PUT /agents/{id}/connectors sets which connector keys the agent may call (what tools it has). POST /agents/{id}/grants grants a specific connected account with optional read/write scopes (which accounts it may use). An agent can only reach what you explicitly grant.