Augeo AI Docs
SDKs

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

ItemRequirement
Browser pageCan insert HTML and load a classic script
Mount nodeAn empty element such as #chat-host exists in the DOM
Host sessionThe host backend has the verified signed-in member
THEO bearerCached before new AugeoAssistant runs
NetworkThe page can call the selected API origin and its own token endpoint

Verified build

NameValue
Personaloyalty-concierge
Bundle globalwindow.AugeoChatSdkLoyaltyConcierge
Custom elementchat-sdk-loyalty-concierge
Evidenced revisionb7909e4564933080f7dbc92e6c4915147906ab60
Emitted versionb7909e45
Script loadingClassic script, then read AugeoAssistant from that global
Mount APInew AugeoAssistant({ container, apiBaseUrl, auth })
ContainerCSS 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.js
packages/chat-sdk/harness/kigo-auth/acceptance.md

The acceptance record names the checksum and the fixture result. Public declarations used for compilation live beside that build.

packages/chat-sdk/types/index.d.ts

Steps

  1. Load the revision-pinned self-hosted script.
  2. Create the cached THEO bearer before mount.
  3. Construct AugeoAssistant with selector #chat-host.
  4. Pass apiBaseUrl for the selected environment.
  5. Use awaited onFailure to replace that cache.
  6. 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

FieldRequiredDescription
containeryesCSS selector resolved with document.querySelector
auth.getTokenyesSynchronous read of the current cached THEO bearer
auth.onFailurenoAwaited recovery for a known recoverable session failure
onErrornoReceives mount and runtime errors
apiBaseUrlyes for a selected environmentAPI origin for that environment
capabilities.events.applicationNamenoStable application slug. Not read from the page URL
capabilities.events.programIdnoNon-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.

EnvironmentapiBaseUrl
productionhttps://api.augeoai.net
named non-productionThat environment's API origin
Script hostscript-srcconnect-src
Self-hosted verified build'self''self' and the selected API origin
Verified CDN artifact onlyhttps://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

GoalPage
Product scope and host dutiesOverview
Root options and auth contractConfiguration
Inline, modal, and sidebar shellsSurfaces
Agent name and partner colorsBranding
Feature groupsCapabilities
Destination writersAnalytics
Public typesAPI
Diagnose mount failuresCommon issues