Capability authentication options
Capabilities authenticate against external systems on two axes:
- Auth type — how the credentials are formatted on the wire (header, query string, OAuth flow, etc.).
- Auth mode — whose credentials are being used (the customer’s own, or one shared credential Atender holds for everyone).
Both are set on the connection, not on the individual capability: open the connection from the systems strip on Settings → Capabilities and use the How do we connect to your system? card. Every capability built on that connection inherits the answer. Get them right and the capability runs cleanly; get them wrong and every call returns 401.
Auth types
How the credentials are formatted on each request.
- None — No authentication header sent. — Public APIs (status pages, public catalogues).
- API Key — A static key sent either as a header or a query parameter you specify. — Most REST APIs. The simplest authenticated option.
- Bearer Token — A token sent in the
Authorization: Bearer <token>header. — OAuth-style services, modern API platforms. - Basic Auth — A username and password base64-encoded into
Authorization: Basic <…>. — Legacy systems, internal services. - OAuth2 — A full OAuth2 flow with authorization endpoint, token endpoint, and refresh handling. Atender stores and refreshes tokens automatically. — Customer-facing systems where each customer authenticates separately.
- Custom Header — A header you define yourself with whatever value or format the API expects. — APIs with non-standard auth schemes, or when you need to send multiple custom headers.
Auth modes
Whose credentials are being used. This is independent of the auth type. The card offers these tiles:
- Shared credentials (
full_access) — One key or login that Atender uses for every customer. — The capability acts as your business — looking up any order, processing any refund. Most internal systems use this mode. - External OAuth (
external_oauth) — The customer’s. They sign in on your provider’s own page and Atender uses the token that comes back. — The customer needs to grant access to their own account in an external system. See Configure External OAuth customer sign-in.
Two further modes exist only on connections already saved on them:
- Customer login (
proxy_auth) — each customer signs in with their own details through a login endpoint you host. It is no longer offered when you set up a new connection, so the tile appears only on a connection that already uses it. - Custom (
custom) — retired. It has no working runtime: nothing mints a pending session and no callback elevates the conversation, so a capability above Public on such a connection can never unlock, and the publish checklist blocks it on the Connection can verify a customer row, telling you to move the capability to an API key or customer-login connection. A connection still on it shows “Currently Custom — no longer offered. Contact support to migrate.”
The card labels the mode picker with the mode’s own status line — “Shared credentials · Configured”, or “External OAuth — not saved yet” — and reminds you that this is only how Atender authenticates to your API: it never means a customer is trusted.
MCP session-key authentication
MCP connections can also use session_key auth for Webhuset-style integrations, where Atender needs short-lived customer-scoped access instead of a static credential on every tool call.
Admins configure the MCP connection with:
- An internal API base URL
- A
svc_live_service token used to mint and revoke session keys - Optionally, a scope allow-list capping what any minted key may ask for
Discovered MCP tools declare the MCP scopes they require. During a verified customer conversation, Atender mints a short-lived whk_live_ key for the union of scopes across that connection’s published MCP capabilities — intersected with the allow-list when one is set — and uses it for the MCP tool call. A key lasts 60 minutes; a sign-in as a different customer revokes the outstanding key and mints a fresh one, and so does any change to the allow-list, the internal base URL, or the service token.
This mode fails closed. Every session-key MCP tool call needs a conversation with a resolved customer, and a capability above Public on such a connection derives the top enforcement level (3) because the minted key is the customer’s credential. If the conversation carries no customer, or the key is missing, expired, or cannot be minted, Atender does not call the tool. There is no static fallback credential.
Choosing the right combination
The two axes combine. The most common pairs:
- API Key + Shared credentials — internal admin APIs the capability calls on behalf of your business.
- OAuth2 + External OAuth — anything where the customer needs to log into their own account.
- Bearer Token + Shared credentials — modern SaaS APIs called with a static service-account token.
- Custom Header + Shared credentials — partner APIs with bespoke authentication.
Token handling for OAuth2
When you pick OAuth2 + External OAuth, Atender:
- Walks the customer through the authorization flow during the conversation
- Stores the access token and refresh token per customer
- Refreshes the token automatically when it expires
- Surfaces token errors in the capability’s execution history so you can diagnose them
You don’t need to write refresh logic yourself.
Identity verification is separate
Auth tells the external system who’s calling. Identity verification is a separate gate Atender adds in front of sensitive capabilities: until the customer has verified, the tool is withheld from the agent entirely, and Atender drives either a one-time code to a channel already on the customer’s account or a sign-in on the connection. The per-capability identity-fields editor (email / order number / zip code answers checked against your records) is gone. See Security levels for how verification levels and action tiers fit together.