Quick start
Quick start
Mount loyalty concierge only after the host has a cached THEO bearer. The browser sends that opaque bearer to Chat. It never sends a mint secret or a Kigo member token.
Prerequisites
| Item | Requirement |
|---|---|
| Browser page | Can insert HTML and load a classic script |
| Mount node | An empty element such as #chat-host exists in the DOM |
| Host session | The host backend has the verified signed-in member |
| THEO bearer | Cached before new AugeoAssistant runs |
| Network | The page can call the selected API origin and its own token endpoint |
Verified build
| Name | Value |
|---|---|
| Persona | loyalty-concierge |
| Bundle global | window.AugeoChatSdkLoyaltyConcierge |
| Custom element | chat-sdk-loyalty-concierge |
| Evidenced revision | b7909e4564933080f7dbc92e6c4915147906ab60 |
| Emitted version | b7909e45 |
| Script loading | Classic script, then read AugeoAssistant from that global |
| Mount API | new AugeoAssistant({ container, apiBaseUrl, auth }) |
| Container | CSS selector string. Not an element or shadow root |
This lifecycle was executed from that revision-pinned self-hosted build.
CDN 0.10.0 and latest were not verified for it.
Do not treat a package manifest version as a CDN release.
packages/chat-sdk/dist/iife/loyalty-concierge/index.jspackages/chat-sdk/harness/kigo-auth/acceptance.mdThe acceptance record names the checksum and the fixture result. Public declarations used for compilation live beside that build.
packages/chat-sdk/types/index.d.tsSteps
- Load the revision-pinned self-hosted script.
- Create the cached THEO bearer before mount.
- Construct
AugeoAssistantwith selector#chat-host. - Pass
apiBaseUrlfor the selected environment. - Use awaited
onFailureto replace that cache. - Call
destroy()when the session ends.
Add a mount container
Create the host element before the constructor runs.
Pass its selector string to container.
<div id="chat-host"></div>Load the verified script
Load the self-hosted loyalty concierge IIFE as a classic script.
Read the constructor from window.AugeoChatSdkLoyaltyConcierge.
<script src="/vendor/chat-sdk/loyalty-concierge/index.js"></script>That served path matches the executed fixture.
Copy the built IIFE to the origin your page already trusts.
A self-hosted page uses script-src 'self'.
Do not add a CDN script origin unless that exact artifact was verified.
Host exchange
The authenticated host endpoint mints the THEO bearer.
The browser calls only that host endpoint.
Derive account_id and the current account-space token from the same verified session.
subject_token is that account_id.
Do not send a profile id, email, or Kigo JWT.
Reject browser account, program, and provider overrides.
programId is an SDK hint, not authorization.
THEO finds or creates the identity in the credential's program.
An existing identity in another program or tenant is rejected.
The host credential and principal must allow each requested scope.
member alone permits member routes; Offers Chat also needs agent:offers-concierge.
Refresh or validate the Kigo session before reminting after upstream rejection.
There is no refresh token.
Use expires_in from the response.
Do not hardcode a lifetime.
POST /api/token
Authorization: Basic base64(<credential_id>:<mint_secret>)
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token=<verified Kigo account_id>
subject_token_type=urn:augeo-ai:params:oauth:token-type:external-account-id
scope=agent%3Aoffers-concierge+member
session_handle=<current account-space token, no Bearer prefix>Return only the validated THEO fields to the browser.
Those fields are access_token, token_type, issued_token_type, expires_in, and scope.
Set cache-control to no-store.
Do not return the mint secret, Kigo token, or provider body.
Initialize after acquisition
Construct AugeoAssistant only after the cache holds a bearer.
auth.getToken must return that string synchronously.
Do not return a Promise.
A returned Promise stringifies in the Authorization header.
Read the latest cache on each call.
Do not mint inside the getter.
import type {
AugeoAssistantOptions as QuickStartAssistantOptions,
AuthFailure as QuickStartAuthFailure,
} from './vendor/chat-sdk/index';
interface QuickStartTheoToken {
access_token: string;
token_type: string;
issued_token_type: string;
expires_in: number;
scope: string;
}
declare function quickStartReadBearer(): string;
const quickStartAuth: QuickStartAssistantOptions['auth'] = {
getToken: () => quickStartReadBearer(),
};
const quickStartOptions: QuickStartAssistantOptions = {
container: '#chat-host',
apiBaseUrl: 'https://api.augeoai.net',
auth: quickStartAuth,
};
function quickStartAcceptFailure(failure: QuickStartAuthFailure): boolean {
return failure.recoverable;
}
void quickStartOptions;
void quickStartAcceptFailure;Omitted surface mounts inline in #chat-host.
Omitted branding.agentName displays THEO.
Required configuration
| Field | Required | Description |
|---|---|---|
container | yes | CSS selector resolved with document.querySelector |
auth.getToken | yes | Synchronous read of the current cached THEO bearer |
auth.onFailure | no | Awaited recovery for a known recoverable session failure |
onError | no | Receives mount and runtime errors |
apiBaseUrl | yes for a selected environment | API origin for that environment |
capabilities.events.applicationName | no | Stable application slug. Not read from the page URL |
capabilities.events.programId | no | Non-authoritative hint. Not authorization |
The container must exist when construction runs.
A missing container fails the mount and calls onError.
API base and CSP
Pass apiBaseUrl explicitly.
The value baked into a build is that build's environment, not a production limit.
| Environment | apiBaseUrl |
|---|---|
| production | https://api.augeoai.net |
| named non-production | That environment's API origin |
| Script host | script-src | connect-src |
|---|---|---|
| Self-hosted verified build | 'self' | 'self' and the selected API origin |
| Verified CDN artifact only | https://sdks.augeoai.net | 'self' and https://api.augeoai.net |
Use 'self' for the authenticated host token endpoint.
Do not combine CDN and self-hosted script origins.
Inline Shadow DOM styles need a separate style-src 'unsafe-inline'.
That style rule is not part of the script or connect policy.
Error contract
Recover only a known recoverable authentication failure.
Known codes are SESSION_EXPIRED, SESSION_REVOKED, and SESSION_INVALID.
recoverable must be true.
Chat accepts the HTTP 401 envelope and one transient stream event.
Bind recovery to the bearer captured for that request.
Deduplicate reports for the same failed bearer.
Ignore a late failure from an old bearer or a disposed session.
Do not render, persist, replay, or resend the stream event.
Malformed data, generic 401 bodies, 403, 404, and outages do not remint.
{"error":{"code":"SESSION_INVALID","message":"Please sign in again.","recoverable":true}}{"type":"data-auth-failure","data":{"error":{"code":"SESSION_INVALID","message":"Please sign in again.","recoverable":true}},"transient":true}Callback differences
Chat getToken returns a string.
Search getToken may return a string or a Promise.
Chat awaits onFailure and does not replay the failed turn.
The next intentional action reads the replacement.
Search awaits optional onFailure, rereads getToken, and retries once.
Search onAuthError is the final code-only notification.
Omitting Search onFailure keeps its existing getter retry.
One failed bearer gets one shared renewal.
A failed, unchanged, or rejected replacement ends that cycle.
Only a later user action or a new session starts another cycle.
import type {
AugeoAssistantOptions as QuickStartAssistantOptions,
AuthFailure as QuickStartAuthFailure,
} from './vendor/chat-sdk/index';
declare function quickStartReadBearer(): string;
const quickStartRecoverable = ['SESSION_EXPIRED', 'SESSION_REVOKED', 'SESSION_INVALID'] as const;
type QuickStartRecoverableCode = (typeof quickStartRecoverable)[number];
declare function quickStartRenew(failure: QuickStartAuthFailure): Promise<void>;
function quickStartIsRecoverable(
failure: QuickStartAuthFailure,
): failure is QuickStartAuthFailure & { code: QuickStartRecoverableCode; recoverable: true } {
return (
failure.recoverable &&
quickStartRecoverable.includes(failure.code as QuickStartRecoverableCode)
);
}
const quickStartRecoveryAuth: QuickStartAssistantOptions['auth'] = {
getToken: () => quickStartReadBearer(),
onFailure: async (failure) => {
if (!quickStartIsRecoverable(failure)) return;
await quickStartRenew(failure);
},
};
void quickStartRecoveryAuth;Show one sign-in action when renewal fails.
Use the message Please sign in again.
Do not show bearer values or provider diagnostics.
Session changes
Call destroy() on logout, account change, or program change.
Clear the cached bearer before another member mounts.
A late mint must not restore the previous bearer.
Same-member renewal leaves the assistant mounted.
The next request reads the replacement through getToken.
import type { AuthFailure as QuickStartAuthFailure } from './vendor/chat-sdk/index';
declare function quickStartAcquire(): Promise<void>;
declare function quickStartReadBearer(): string;
declare function quickStartRenew(failure: QuickStartAuthFailure): Promise<void>;
declare function quickStartIsRecoverable(failure: QuickStartAuthFailure): boolean;
async function quickStartMount(): Promise<void> {
await quickStartAcquire();
const assistant = new window.AugeoChatSdkLoyaltyConcierge.AugeoAssistant({
container: '#chat-host',
apiBaseUrl: 'https://api.augeoai.net',
auth: {
getToken: () => quickStartReadBearer(),
onFailure: async (failure) => {
if (!quickStartIsRecoverable(failure)) return;
await quickStartRenew(failure);
},
},
});
assistant.destroy();
}
void quickStartMount;Name the application
Pass capabilities.events.applicationName for the implementing application.
Set a stable slug at initialization.
Do not copy it from the page URL.
Both applicationName and environment are optional.
capabilities: {
events: {
applicationName: 'theo',
},
}A partner embed passes its own slug.
capabilities.events.environment is optional integrator metadata.
It is not a deployment name.
Tear down
Destroy the instance when the host page unmounts the chat area.
assistant.destroy();After destroy(), the instance is inert.
Construct a new AugeoAssistant if the member needs the widget again.
Full example
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Host site</title>
</head>
<body>
<div id="chat-host"></div>
<script src="/vendor/chat-sdk/loyalty-concierge/index.js"></script>
<script src="/host/browser.js"></script>
</body>
</html>The host script acquires the bearer, then constructs the assistant.
Keep that script outside the inline page so script-src 'self' holds.
Next steps
| Goal | Page |
|---|---|
| Product scope and host duties | Overview |
| Root options and auth contract | Configuration |
| Inline, modal, and sidebar shells | Surfaces |
| Agent name and partner colors | Branding |
| Feature groups | Capabilities |
| Destination writers | Analytics |
| Public types | API |
| Diagnose mount failures | Common issues |