Configuration
Configuration
Pass AugeoAssistantOptions to new AugeoAssistant(config).
Only container and auth.getToken are required by the constructor.
Pass apiBaseUrl for the environment you selected.
Every other root field is optional.
Prerequisites
| Item | Value |
|---|---|
| Persona | loyalty-concierge |
| Bundle global | window.AugeoChatSdkLoyaltyConcierge |
| Mount node | A DOM element matches your container selector |
| Token | A cached THEO bearer exists before construction |
| Evidenced revision | b7909e4564933080f7dbc92e6c4915147906ab60 |
Load the revision-pinned self-hosted loyalty script first.
CDN 0.10.0 and latest were not verified for this lifecycle.
packages/chat-sdk/dist/iife/loyalty-concierge/index.jsRoot fields
| Field | Required | Default | Effect |
|---|---|---|---|
container | yes | none | CSS selector string for the existing mount node |
auth.getToken | yes | none | Synchronous read of the current THEO bearer |
auth.onFailure | no | none | Awaited recovery for a known recoverable failure |
apiBaseUrl | selected environment | baked build origin | API origin for that environment |
onError | no | shared logger | Receives mount and runtime errors |
branding | no | THEO, product theme | Sets agent name and partner colors |
surface | no | inline | Selects the presentation shell |
capabilities | no | product defaults | Enables feature groups |
Read Privacy to configure program policy links through capabilities.privacy.
Container
container is a CSS selector string.
Construction queries it with document.querySelector.
It is not an element or a shadow root.
new AugeoAssistant({
container: '#chat-host',
apiBaseUrl: 'https://api.augeoai.net',
auth: { getToken: () => cachedTheoBearer },
});That selector must match an element that already exists.
A missing node throws, skips the mount, and calls onError.
Script loading
Load the verified IIFE as a classic script.
Then read AugeoAssistant from window.AugeoChatSdkLoyaltyConcierge.
<script src="/vendor/chat-sdk/loyalty-concierge/index.js"></script>The executed fixture served that path from the revision above.
Its emitted version was b7909e45.
Do not infer a CDN release from a package manifest.
Host exchange
The host backend exchanges the verified member for an opaque THEO bearer.
The browser receives only the validated THEO response.
It never receives the mint secret or the Kigo member token.
subject_token is the verified Kigo account_id.
Do not send a profile id, email, or Kigo JWT.
The host endpoint rejects browser account, program, and provider overrides.
capabilities.events.programId is a 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 to time the cached renewal.
Do not hardcode a lifetime.
Return cache-control: no-store.
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>The browser response fields are access_token, token_type, issued_token_type, expires_in, and scope.
Do not add a refresh token or a provider diagnostic field.
Auth token
Acquire the THEO bearer before mount.
auth.getToken must return a string synchronously.
The widget calls it when it builds the Authorization header.
Read the latest cache.
Do not mint inside the getter.
import type {
AugeoAssistantOptions as ConfigAssistantOptions,
AuthFailure as ConfigAuthFailure,
} from './vendor/chat-sdk/index';
declare function configReadBearer(): string;
const configAuth: ConfigAssistantOptions['auth'] = {
getToken: () => configReadBearer(),
};
const configOptions: ConfigAssistantOptions = {
container: '#chat-host',
apiBaseUrl: 'https://api.augeoai.net',
auth: configAuth,
};
void configOptions;
void (null as ConfigAuthFailure | null);A returned Promise stringifies in the Authorization header.
Auth failure
auth.onFailure is optional.
Chat awaits it for a known recoverable failure.
It does not replay the failed turn.
The next intentional action reads the replacement through getToken.
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 the callback to the bearer captured for that request.
Deduplicate HTTP, stream, and concurrent reports for that bearer.
Ignore a late report 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.
One failed bearer gets one renewal in that cycle.
A failed, unchanged, or rejected replacement ends the cycle.
Only a later user action or a new session starts another cycle.
Show one sign-in action.
Use Please sign in again.
Do not show bearer values or provider diagnostics.
{"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}import type {
AugeoAssistantOptions as ConfigAssistantOptions,
AuthFailure as ConfigAuthFailure,
} from './vendor/chat-sdk/index';
declare function configReadBearer(): string;
const configRecoverable = ['SESSION_EXPIRED', 'SESSION_REVOKED', 'SESSION_INVALID'] as const;
type ConfigRecoverableCode = (typeof configRecoverable)[number];
declare function configRenew(failure: ConfigAuthFailure): Promise<void>;
const configRecoveryAuth: ConfigAssistantOptions['auth'] = {
getToken: () => configReadBearer(),
onFailure: async (failure) => {
if (!failure.recoverable) return;
if (!configRecoverable.includes(failure.code as ConfigRecoverableCode)) return;
await configRenew(failure);
},
};
void configRecoveryAuth;Callback differences
| Callback | Chat | Search |
|---|---|---|
getToken | Synchronous string | String or Promise |
onFailure | Optional awaited recovery. No automatic replay | Optional. Awaited before one retry |
onAuthError | Not a Chat callback | Final notification. Code only |
| Omitted recovery hook | No Chat recovery callback | Existing getter-and-401 retry remains |
Search mounts with createAugeoSearch and an existing element.
Chat does not accept that element as container.
API origin
Pass apiBaseUrl for the selected environment.
Omitting it uses the origin baked into that build.
That baked origin is not a hardcoded production limit.
| Environment | apiBaseUrl |
|---|---|
| production | https://api.augeoai.net |
| named non-production | That environment's API origin |
apiBaseUrl: 'https://api.augeoai.net'A blank override is ignored. The baked origin of the selected build is used instead.
Script and connect policy
| 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.
Errors
onError receives mount and runtime errors.
Omit it to use the shared logger.
onError: (error) => {
window.hostTelemetry?.captureError?.(error);
}A missing container is reported here. Keep the callback cheap and side-effect safe. Do not log bearers or provider bodies from auth callbacks.
Branding pointer
branding.agentName defaults to THEO.
branding.theme recolors partner-branded surfaces.
See Branding for palette, ramp, and override rules.
Surface pointer
surface.type is the only discriminant.
Allowed values are inline, modal, and sidebar.
Omitted surface resolves to inline.
See Surfaces for every shell field and default.
Events application identity
capabilities.events.applicationName names the implementing application.
The field is optional.
Set it when you construct the assistant.
The slug is not read from the page URL.
Existing events configuration keeps working when the field is omitted.
| Field | Required | Default | Effect |
|---|---|---|---|
capabilities.events.applicationName | no | none | Stable application slug on requests and telemetry |
capabilities.events.environment | no | none | Integrator environment name, kept nested |
capabilities.events.programId | no | none | Non-authoritative hint. Not an authorization claim |
Pass a non-PII slug. Do not include a user, session, token, or URL.
capabilities: {
events: {
applicationName: 'theo',
environment: 'sandbox',
},
}A Theo-owned page passes theo.
A partner embed passes its own slug.
events: true, omitted events, and events: false send no slug.
environment stays under data.context.host.
It is not a CloudEvents attribute.
Omit it when you have no integrator environment name.
dev, stage, and prod name deployment streams, not this field.
An environment without a kept slug is dropped.
Requests send the slug on X-Attribution-Application-Name.
Telemetry copies it to data.context.host.applicationName.
The page location stays {href, title, referrer}.
Capabilities pointer
capabilities groups optional features such as history, chat, events, and analytics.
Each group is a boolean or an options object.
See Capabilities for the feature map.
Minimal construct
const { AugeoAssistant } = window.AugeoChatSdkLoyaltyConcierge;
const assistant = new AugeoAssistant({
container: '#chat-host',
apiBaseUrl: 'https://api.augeoai.net',
auth: { getToken: () => cachedTheoBearer },
});That construct fills #chat-host inline.
The agent name is THEO.
Partner colors stay at product defaults.
Optional construct
const assistant = new AugeoAssistant({
container: '#chat-host',
apiBaseUrl: 'https://api.augeoai.net',
auth: {
getToken: () => cachedTheoBearer,
onFailure: (failure) => renewTheoBearer(failure),
},
onError: (error) => console.error(error),
branding: {
agentName: 'Ava',
theme: { palette: { primary: '#6119ea' } },
},
surface: { type: 'modal', openOnMount: false },
capabilities: {
events: {
applicationName: 'theo',
environment: 'sandbox',
programId: 'prog_1',
},
},
});openOnMount: false keeps the modal closed until Ask AI or the FAB.
capabilities.events.applicationName is the application slug, not the agent name.
programId does not authorize the exchange.
agentName: 'Ava' replaces the default THEO in the header.
Hex palette.primary derives partner tokens and a brand ramp.
Session lifetime
Call destroy() on logout, account change, or program change.
Clear the cached bearer first.
A late response must not restore it.
Same-member renewal keeps the mounted assistant.
Token-scoped requests then read the replacement.
import type { AugeoAssistantAuth } from './vendor/chat-sdk/index';
declare function configAcquire(): Promise<void>;
declare function configClearBearer(): void;
declare const configRecoveryAuth: AugeoAssistantAuth;
async function configMountForSession(): Promise<void> {
await configAcquire();
const assistant = new window.AugeoChatSdkLoyaltyConcierge.AugeoAssistant({
container: '#chat-host',
apiBaseUrl: 'https://api.augeoai.net',
auth: configRecoveryAuth,
});
configClearBearer();
assistant.destroy();
}
void configMountForSession;Tear down
Call assistant.destroy() when the host route or session ends.
The instance is inert after destroy.
Related pages
| Topic | Page |
|---|---|
| Product scope | Overview |
| Minimal embed | Quick start |
| Shell fields | Surfaces |
| Agent name and theme | Branding |
| Feature groups | Capabilities |
| Member intents | Events |
| Destination writers | Analytics |
| Public types | API |
| Mount failures | Common issues |