Connectors & connected accounts

A connector is a third-party integration a user connects once — Gmail, Microsoft 365, GitHub, Adobe, Slack, Stripe, Notion, … A connected account is that user's live credential row. Tool agents then act as that user: google-gmail reads the mailbox of whoever owns the ozk_ key that made the call. Nothing about the credential ever appears in the API.

Three things are easy to confuse:

7.1 Two credential tiers

Both land in user_credentials on the compliance database, AES-256-GCM encrypted with per-scope keys; every read is audited (core/core-secrets/CLAUDE.md). Agents never receive raw tokens from callers — the platform injects them at run time, which is why params names such as api_key or token are stripped by contract validation.

7.2 How a connected account flows into an API call

your app ──ozk_ key──► One API ──user_id──► engine ──► google-gmail agent
                                                          │ resolveApiKey(google, user)
                                                          ▼
                                            user_credentials row?  yes → call Gmail as the user
                                                                   no  → outcome: needs_connection

Without a connection the agent answers with a structured refusal (success: false, outcome: needs_connection) and the tools plane returns 424 connection_required:

{ "error": { "code": "connection_required", "message": "Connect your Google account in Studio → Integrations to use google-gmail", "outcome": "needs_connection", "connect": { "provider": "google", "method": "oauth", "link": "POST /v1/connections/google/link" } } }

connect is the way in: the connector (provider), how it connects (method: oauth, api_key or wallet) and the route that starts it (7.3). Every 424 from the tools, agents, workflows and Agent Call routes carries it when the agent is connection-tier; the Markdown and text wires print it as connect: POST /v1/connections/<provider>/link under the execution footer. credential_required (needs_api_key) carries it the same way.

The same run with a connection returns 200 { ok: true, content } — live example from 2026-09-18 with a Microsoft 365 connection on the calling account (microsoft-todo, operation list_lists, request id 00000000-0000-4000-8000-000000000003).

Which agents need what: the credential field on every card (GET /v1/tools/<id>, the lists, GET /v1/discovery/search) — { "tier": "platform" } or { "tier": "connection", "provider", "method" }; the Credential column in the tool catalog is that field. The rule of thumb: google-* needs the google connector (except the key-based tool APIs google-books, google-translate, google-places-agent, google-cloud-iot-agent), microsoft-* needs Microsoft 365 (connector id azure), adobe-* Adobe (not adobe-pdf-services), gitlab-agent GitLab, stripe-agent a Stripe key; search/scrape/document tools run on platform keys.

7.3 How your testers connect an account

Connecting is an API call. The ozk_ key that makes the call owns the connection, and no Studio login is needed:

The hosted link is https://studio.plungeai.com/connect/<token>: signed, single-use, valid 15 minutes, and it works without a Studio session — send it to the person who owns the account. The page opens with who is asking — your Studio name, else your email — and says that your agents will act on the account on their behalf until they disconnect it. For an OAuth provider the page is Continue with <Provider> → approve at the provider → back to your return_url (an https URL you gave, with ?connected=<provider> added) or, without one, a confirmation page. Where Studio has no OAuth app for the provider the page is a key form: the pasted key is checked and stored the same way as POST /v1/connections/:provider. A tampered or expired link is 404, a used one 410.

curl -s -X POST "https://api.plungeai.com/v1/connections/google/link" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H "Content-Type: application/json" \
  -d '{"return_url":"https://example.com/done"}'

Your customers (on_behalf_of). Name a customer with any id you own — 1 to 128 characters of A-Z a-z 0-9 _ . - (no .., no :) — and the connection is that customer's, not yours: it is stored under your key and your customer id, so two developers who use the same id never collide, GET /v1/connections shows only the account you ask for (yours, or the one on_behalf_of names) and nobody can reach a customer of another key. An empty on_behalf_of is refused, never read as your own account.

To run an agent as a customer, send the same id on the call: POST /v1/execute with on_behalf_of: cust_42 next to agent:. A connection-tier agent then uses the account connected under that id (and answers 424 with connect when that customer has none) — never yours; the run, its billing and a saved agent stay yours, and the result is returned to you as usual. It is a wire key, like format: it never reaches the agent as a field. It is accepted on POST /v1/execute only: the per-id doors (/v1/tools/{id}/execute, /v1/agents/{id}/execute, /v1/workflows/{id}/execute and their stream variants) answer 400 invalid_body rather than quietly running as you.

Provider ids are the connector ids of 7.4 — the credential.provider of a card or the connect.provider of a 424 names the one to use (google, azure for Microsoft 365, github, slack, stripe, …).

The same connection can be made in Ocean Studio (https://studio.plungeai.com), where a signed-in user connects their own account in a browser:

1. Studio → Integrations → Browse connectors → pick the provider.
2. OAuth connector: Continue with <Provider> → approve → back in Studio as Connected. API-key connector: paste the key → it is probed live → Connected (or an inline "rejected" error).
3. Verify with the API: run the agent with the same user's ozk_ key — the needs_connection outcome disappears.

The Studio endpoints behind those buttons (session cookie, not API key — listed so you know what happens, not for you to call): GET /api/connections (yours), GET /api/connections/providers (public: every OAuth provider and its scopes), GET /api/auth/oauth/:provider/start, POST /api/connections/api-key (400 when the live probe rejects the key), DELETE /api/connections/:provider. Special flows exist for the Circle agent wallet (/api/connections/circle-agent-wallet/init|verify), retailer logins such as Amazon (/api/connections/retailer/connect) and QR/browser logins such as WhatsApp (/api/connections/browser-session/*) — those connect in Studio only.

curl -s "https://studio.plungeai.com/api/connections/providers"

Redirect URIs and OAuth app registration are platform-side — testers never configure anything at the provider.

7.4 The connector catalog

The registry lists 802 connector cards (GET /v1/discovery/search?kind=connectors&limit=100, page with offset until total; live 2026-09-29). Every card carries connector.auth — never null:

curl -s "https://api.plungeai.com/v1/discovery/search?kind=connectors&limit=3" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"

curl -s "https://api.plungeai.com/v1/discovery/cards/connector/slack" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"

OAuth apps registered on the platform today (client id wired in the Studio worker, wrangler-templates/template.wrangler.ocean.jsonc ↔ core/core-secrets/oauth-providers.ts): google (Workspace: Drive, Gmail, Calendar, Contacts, Tasks, Docs, Sheets, Slides, Analytics, Search Console, Merchant Center, Business Profile, YouTube; google-youtube also connects YouTube on its own), azure (Microsoft 365: OneDrive, Outlook, Calendar, Teams, SharePoint, To Do, Planner, OneNote, Office files), adobe (Creative Cloud, Express, Photoshop, Lightroom, Stock, Experience Platform, Journey Optimizer), github, gitlab, bitbucket, slack, salesforce, hubspot, shopify. Provider entries also exist for sonos, spotify, tesla, facebook, linkedin, twitter, reddit, tiktok, pinterest, snapchat, intuit, square, zoom, sentry, notion — their cards show in Studio, but the OAuth app is not registered yet, so Continue with … bounces with oauth_not_configured; connect those with an API key where the card offers one.

By category (ids as the registry spells them):

7.5 The connector proxy — /v1/connect/:provider/proxy/*

For providers you would otherwise call directly, the inference gateway offers a metered pass-through (inference/gateway/src/routes/connector-proxy.ts): one ozk_ key, one bill, transparent bytes in both directions (streaming included, no body transformation).

Example (one metered provider call, so it carries no # verify marker):

curl "https://api.plungeai.com/v1/connect/brave-search/proxy/res/v1/web/search?q=cloudflare+workers" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"

Each call is metered as a connector_requests row and appears in the Dashboard next to your inference spend. Prefer the tools plane when you want the agent's judgement (result formatting, pagination, outcome vocabulary); use the proxy when you want the provider's raw API with one key and one bill.