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 sign-in 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 Authentication Mode

1. Open the capability, and go to its connection’s authentication settings.
2. Set Authentication Mode to External OAuth.
3. Fill in the OAuth2 fields:

• Redirect URL / Callback URL — Read-only value generated by Atender. Copy this exact URL into the OAuth provider’s allowed redirect URI or callback URL setting.
• Authorize 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.
• Client ID — Issued by the provider for this connection.
• Client Secret — Issued by the provider. Stored encrypted — once saved, the field shows as set rather than displaying the value back to you.
• Scopes — Space- or comma-separated list of scopes to request at authorize time. Request only what the capability actually needs to act and to read userinfo.
• User-info URL — The provider endpoint Atender calls with the new access token to retrieve the customer’s identity claims after login.

Leaving Client ID or User-info URL blank keeps the connection from qualifying as a working sign-in method — both are required for the mode to count as configured (see the checklist 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 capability using External OAuth can’t be published until the connection passes two checklist rows:

• oauth_config — Authorize URL, Token URL, Client ID, and a client secret are all present.
• oauth_userinfo — the User-info URL is set and the customer field binding resolves to a claim in its response.

If you edit the authentication settings again later without touching the underlying OAuth fields — for instance, re-parsing an imported API definition — Atender preserves your saved Client ID, Client Secret, and User-info URL rather than wiping them. If you do change something that affects gating (adding or removing an Authorize URL, for example), re-check the checklist: the capability’s security level is re-derived from the connection whenever the auth config changes, so a capability that previously required sign-in can’t silently drop to a lower tier just because a field was edited.

What the customer sees

Once the connection is configured and the checklist passes, any Act-tier tool gated 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 sign-in card instead of running it.
2. The customer follows the card to the provider’s own login page (the Authorize 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 so the gated capability can now run, scoped to that customer.

If the provider callback comes back with no resolvable identity, or with an error, Atender fails closed: the customer sees a sign-in error rather than being handed a session bound to the wrong person or to nobody.

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 they’re shown the sign-in card again.

Troubleshooting

• Widget never shows a sign-in card, tool just stays withheld — Authorize 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 or callback URL setting. 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 always starts a new identity binding and does not inherit the previous customer’s data.
• Capability drops back below Act tier after an unrelated edit — An authentication-config-only save didn’t re-trigger a security-level re-derivation; re-open and re-save the connection’s auth settings.