Configure External OAuth Customer Sign-In

External OAuth is a connection authentication mode for capabilities. Instead of Atender holding a shared credential for a connection, the customer signs in on the connection’s own OAuth provider — their bank, their booking platform, their account portal — and Atender uses the token that comes back to act on their behalf. This is the right mode whenever a capability must act scoped to the specific customer in the conversation, not to a tenant-wide service account.

When External OAuth is configured correctly, gating a tool to it does three things automatically at runtime: - shows the customer a login card in the widget before the tool can run, - mints a session from the provider’s callback and elevates the conversation so the identity carries through the conversation, - refreshes the access token behind the scenes as it nears expiry, persisting the rotated refresh token.

Before you start

External OAuth only makes sense for a capability whose connection talks to a provider that supports OAuth2 authorization-code login, and where the provider can hand back some identifying claim about the customer (an email, a customer ID, an account number) in its userinfo response. If your connection doesn’t have a per-customer identity to bind, use a different authentication mode.

Setting the connection’s auth mode

1. On Settings → Capabilities, open the connection from the systems strip (or from the capability’s own action picker).
2. In the How do we connect to your system? card, pick the External OAuth tile — “Customers sign in on your provider’s page”.
3. Fill in the OAuth2 fields:

• Redirect URL — register this at your provider — Read-only value generated by Atender. Copy this exact URL into the OAuth provider’s allowed redirect URI setting, on the OAuth client that owns the Client ID below.
• Authorization URL — The provider’s customer-facing login and consent endpoint. The customer is redirected here to sign in and approve access.
• Token URL — The provider’s server-side token endpoint. Atender exchanges the authorization code and refresh tokens here, server to server.
• Client ID — Issued by the provider for this connection.
• Client secret — Issued by the provider. Stored encrypted and never read back — once saved, the field shows “•••••••• (saved)”; leave it blank to keep it, or type a new value to replace it.
• Scopes (comma-separated) — The scopes to request at authorize time. Request only what the capability actually needs to act and to read user info.
• User info URL — The provider endpoint Atender calls with the new access token to retrieve the customer’s identity claims after login.

Both the Authorization URL and the Client ID are needed before the connection counts as a customer sign-in at all — the Client ID is required because the documentation parser auto-fills an authorization URL on legacy rows that were never really configured, and an authorize URL alone would gate capabilities behind a flow that cannot run. The User info URL is a separate requirement, enforced by the publish checklist rather than by the sign-in test (see below).

Binding the customer field

After a successful sign-in, Atender calls the User info URL and reads the JSON response. The field you map here — the customer field binding — tells Atender which claim in that response identifies the customer (for example, an email or customer_id key in the provider’s userinfo payload). That value is written into the conversation’s session variables and is what scopes every subsequent tool call to this specific customer.

The full userinfo document is also kept as evidence on the sign-in — so if the provider returns a name or email, it can surface on the customer’s identity badge in the conversation, the same way a JWT-based sign-in would.

Get the field mapping right before you publish: a capability that can’t resolve a customer identity from userinfo fails the sign-in closed rather than guessing, so the customer is left unable to proceed instead of being bound to the wrong record.

Publish checklist requirements

A gated (Read, Act or Transact) capability using External OAuth adds two rows to the publish checklist, on top of the rows every capability has:

• Customer sign-in (OAuth) configured — Authorization URL, Token URL, Client ID and a client secret are all present. The two URLs must also parse as http/https; a green row over a malformed value would send the customer’s sign-in click into a bare 500.
• User info endpoint set — the User info URL is filled in. This row checks only that the URL is there. Whether a claim in its response actually names the customer is the separate Your API knows who is asking row, which reads the customer field on the connection.

If you edit the authentication settings again later without touching the underlying OAuth fields — for instance, using Try Extract to pull the OAuth URLs back out of the stored endpoints — Atender merges into what is already saved, so your Client ID, client secret and User info URL survive. If you do change something that affects gating (adding or removing an Authorization URL, for example), re-check the checklist: the capability’s security level is re-derived from the connection whenever the auth config changes, and that re-derivation can only raise a capability’s level, never lower it — so a capability that previously required sign-in can’t silently drop to a weaker gate just because a field was edited.

What the customer sees

Once the connection is configured and the checklist passes, any gated tool behind this connection is withheld from the conversation until the customer has a live session:

1. The AI attempts the gated action and the widget shows a login card — by default a Log in to your account link — instead of running it.
2. The customer follows the card to the provider’s own login page (the Authorization URL) and signs in there — Atender never sees their provider credential.
3. The provider redirects back to Atender’s callback with an authorization code. Atender exchanges it at the Token URL, calls the User info URL, and binds the customer field from the response.
4. The conversation is elevated to level 3 for this connection, so the gated capability can now run, scoped to that customer.

If the provider callback comes back with an error, or the User info URL is configured but resolves no customer identity, Atender fails closed: the sign-in is not activated at all — the customer sees an error page rather than a session bound to the wrong person or to nobody, and any earlier sign-in on the conversation is left untouched rather than torn down over what may be a transient fault.

Token refresh

Access tokens from the provider are typically short-lived. Atender checks token freshness at execution time and refreshes automatically against the Token URL when a token is close to or past expiry, persisting a rotated refresh token if the provider issues one. This happens transparently — the customer does not need to sign in again mid-conversation unless the provider’s refresh token itself has expired or been revoked, in which case the session is expired and the next turn withholds the tool and offers the login card again.

Troubleshooting

• Widget never shows a login card, tool just stays withheld — Authorization URL or Client ID missing — the connection doesn’t qualify as a sign-in method yet.
• Provider shows redirect_uri mismatch or rejects the callback — Copy the Redirect URL shown in the External OAuth card and register that exact URL with the provider’s allowed redirect URI setting, on the OAuth client that owns the Client ID. Escalate for deployment help only if the shown URL has the wrong host or base URL for the environment.
• Customer signs in but the capability still won’t act — User info URL not set, or the customer field binding doesn’t match a key the provider actually returns.
• Customer is bound to the wrong identity on a shared device/conversation — Make sure you’re not reusing a conversation across customers without expecting a fresh sign-in — a new sign-in supersedes and revokes the earlier one on that conversation and connection, and does not inherit the previous customer’s data.
• Customer gets an error page immediately after signing in — The User info URL is set but returned nothing that maps to a customer — a wrong URL, a wrong customer-field mapping, or a provider fault. The sign-in is deliberately not activated in that case; fix the mapping rather than retrying the link.