Connecting accounts
A connector returns real data only after the owning organization connects an account for it. Each connector declares how it authenticates; the agent resolves and decrypts the right credential per call.
Auth flows
Each service declares one auth flow. The catalog uses the first three; mcp_oauth exists only for an MCP server the user adds:
| Auth flow | Description |
|---|---|
credentials | An API key, token or login and password pasted into the connect form. Most of the catalog connects this way. |
device_code | The user confirms the connection on the provider's site with a short code, and the platform collects the token (Yandex services). |
popup_oauth | OAuth in a popup window: the user approves access, and the token is stored and refreshed automatically (Google, GitHub, HeadHunter, Ozon, T-Bank, the Bitrix24 app). |
mcp_oauth | Only for an MCP server the user adds: OAuth of that server with dynamic client registration and PKCE in a popup. |
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 app, under Settings → Connectors: the form asks for exactly the fields the connector declares, a popup-OAuth service opens the provider's window, a device-code service shows the code to confirm. When a call needs an account that isn't connected yet, the agent shows a connect card right in chat (the request_form tool). A second cabinet of the same service is added from the same place under its own name.
The connector's card in the app is where a connection is managed: who may use it (visibility), its stored fields, its webhook URL and disconnecting it. Connecting and managing accounts is not part of the integrator API: an organization key opens /v1 and the MCP server, which reach connected accounts but do not connect them.
Credential storage
Connected credentials are encrypted at rest. An account belongs to whoever connected it; visibility private keeps it theirs, org opens it to the whole organization. When a connector is called, the platform injects the addressed account's secret into the request itself. Connector secrets (API keys, tokens, passwords) never enter the sandbox environment: code reaches a connector through the host, which holds its credentials. os.environ carries only a connection's non-secret identifiers, the user's own variables and the variables an Environment names. Only someone who manages the connection can view the stored value on the connector's card, and every view is written to the audit log.
Multiple accounts (cabinets)
A single service can hold several connected accounts: multiple Ozon cabinets, two WB sellers. Each is addressed with a suffix on the service (ozon:2, ozon:Top Zip). See Calling a connector.
Granting connectors and credentials to an agent
An agent calls only the connectors it is allowed, and may use the connected accounts of whoever it works for, except those switched off for it. The grant is two layers, both on the agent's integrations card in the app:
Allow connectors
The list of connectors decides what tools the agent has (wildberries, ozon, …). A connector the agent isn't allowed simply isn't in its toolset.
Choose its accounts
A switch per connected account decides which accounts it may use: an allowed connector whose accounts are all switched off 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 not switched off for it; everything else is out of scope. The same holds when the agent is called over /v1 by its handle.
See Agents for how agents are addressed from code.
Frequently asked questions
What auth flows do connectors use?
Each service declares one of four auth flows: credentials (an API key, token or password pasted into the form), popup_oauth (OAuth in a popup), device_code (the user confirms on the provider's site with a short code) and mcp_oauth, which only an MCP server the user adds uses. 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. When a connector is called, the platform injects the addressed account's secret into the request itself. Connector secrets (API keys, tokens, passwords) never enter the sandbox environment: code reaches a connector through the host, which holds its credentials. os.environ carries only a connection's non-secret identifiers, the user's own variables and the variables an Environment names.
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 addressed with a suffix on the service: ozon:2 or ozon:Top Zip.
How does an agent get access to a connector and its credentials?
In two layers, both set on the agent's integrations card in the app. The list of connectors decides what tools the agent has; a per-account switch decides which connected accounts it may use. An agent reaches the accounts of the person it runs for, minus the ones switched off. The agent owner's connections never reach teammates: a teammate runs a shared agent on their own connections, limited to the connectors they accepted.