Credentials — Technical Reference
This page describes how credentials work beneath the UI, in technical terms, for developers and technically-inclined users. It focuses on the model and observable behavior, not implementation internals.
Architecture model
A credential is a named record that holds the secrets a tool or channel needs to call an outside service. Agents never see the raw secrets — they only see a normalized handle ("use credential N"), and the platform substitutes the secret values at the moment of the outgoing request.
Every credential has two parts:
- A parent record — the user-visible identity: label, owning user, auth family, provider, status.
- A type-specific child — the actual secret values, encrypted at rest, only readable by the request-time tool runtime.
This split keeps the agent transcript and the credential listing free of secrets, even when several credentials exist for the same provider.
Auth families
Credentials are grouped by the shape of the authentication the outside service requires, not by the provider. Five families cover virtually every public API:
| Family | What it carries | Used at request time as |
|---|---|---|
| basic | Username + password | Authorization: Basic … header |
| bearer | A long-lived secret token | Authorization: Bearer … header |
| apikey | A static key string | A header or a query parameter, per the service's docs |
| oauth2 | A long-lived access grant signed via the provider | An Authorization header refreshed automatically when it nears expiry |
| thirdparty | A platform-native sign-in (e.g., Meta/Facebook for WhatsApp, Instagram, Messenger) | The platform-specific signed token the channel expects |
Storage model
- The parent record stores the label, family, provider, owner and status (active / expired / disabled). It does not store the secret.
- The child record stores the family-specific secret values, encrypted at rest.
- A credential can be shared across many tools and channels — there is one stored secret, used by many consumers.
- When a credential is deleted, every tool and channel that used it is left without access; the platform shows a clear error rather than silently failing.
The agent runtime only ever holds the parent record's ID. The child record is read on the fly when a request is about to leave the platform.
OAuth sign-in flow
For oauth2 credentials, the user signs into the outside service inside a pop-up window. The user-facing experience is "log in with Google / Microsoft / Notion / etc." — there are no client IDs, secrets, or redirect addresses to paste.
- The grant is long-lived — the user does not have to sign in again on every use.
- When a grant approaches expiry, the platform refreshes it in the background so calls keep working.
- If a refresh is refused (revoked at the provider), the credential is marked expired and the user is asked to reconnect.
thirdparty (native Meta sign-in) uses the same pop-up shape but produces a Meta-specific signed token used directly by WhatsApp, Instagram, and Messenger channels.
AI-Credentials flow
When a user picks an unfamiliar service, an AI helper sets up the credential by following a fixed lifecycle:
- Research is a short, automated scan of the provider's own documentation — no scraping of private dashboards.
- The guided steps are produced once the AI has identified the auth family. They are plain-language ("In your account, go to Settings → API Keys, click Create, copy the key, paste it here").
- The connect step is the only place secrets are entered. They are encrypted before storage and never echoed back.
- Verify does one real call to a safe read-only endpoint; failure rolls the credential back to the previous step so the user can correct a typo.
The same flow handles single-credential setup and the "set up several credentials at once" batch flow.
How tools consume a credential at runtime
When an agent is about to call a tool that uses a credential, the platform:
- Looks up the parent record by ID and confirms it is still active.
- Reads + decrypts the child record on the fly.
- Substitutes the secret into the right place for the auth family (header, query parameter, or signed token).
- Sends the request to the outside service.
- Discards the decrypted secret from memory once the request is complete.
- The agent never sees the secret in its prompt or its execution context.
- Logs and traces store the credential ID, never the secret value.
- A failed call returns a normal error to the agent; the agent decides whether to retry or surface the error.
Native (Meta) credentials
WhatsApp, Instagram, and Messenger use a single platform-native credential signed via Facebook. This one credential covers all three channels, and is created through a dedicated sign-in pop-up (not the generic OAuth flow) because the provider issues a Meta-specific token shape rather than a standard one.
Because each channel can only attach one native credential at a time, a given WhatsApp business number, Instagram account, or Messenger Page maps to one agent.
Limits and guarantees
- A credential is owned by one user and only visible to that user (and explicit shares).
- Secret values are encrypted at rest and decrypted only at the moment of an outgoing request.
- A credential can be reused by any number of tools and channels — there is one stored secret per credential, regardless of how many consumers use it.
- The agent only ever holds the credential's ID, never the secret.
- Expired or revoked credentials surface a clear reconnect prompt rather than silently failing.
What's next
- Credential types — the five families in plain language
- AI Credentials — the AI-guided setup flow
- Meta credentials — the WhatsApp / Instagram / Messenger sign-in