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, your team’s, a service account, or a custom flow).
Both are picked when you configure an API for the capability. 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.
- External OAuth — The customer’s. The customer goes through OAuth in-conversation; the capability acts on their behalf. — The customer needs to grant access to their own account in an external system (Google Calendar, GitHub, etc.).
- Proxy Auth — Your team’s, proxied through your own backend. — You want to keep the actual API credentials on your side, with Atender forwarding the customer’s requests through a proxy you control.
- Full Access — A single service account with broad access. — The capability acts as your business — looking up any order, processing any refund. Most internal systems use this mode.
- Custom — A flow you define yourself. — Edge cases none of the above cover — multi-step token exchanges, signed requests, etc.
Choosing the right combination
The two axes combine. The most common pairs:
- API Key + Full Access — 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 + Full Access — modern SaaS APIs called with a static service-account token.
- Custom Header + Full Access — 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 — the AI asks for an email, order number, or zip code and won’t run the capability until the customer’s answer matches your records. See Security levels for how identity verification, security levels, and consent tracking fit together.