Guanta authenticated widget example

This framework-free PHP application demonstrates how a customer application can give a standard Guanta chat widget the verified identity of a logged-in user.

The important part of this example is the server-to-server identity exchange. The application continues to own login, passwords, sessions, user records, and authorization. Guanta receives only the trusted user identifier and display name that the application backend chooses to assert.

The included CSV login is intentionally small and is not a production authentication system. It exists only so the complete integration can be run and inspected without a framework or database.

The same guide is also available as a standalone HTML document.

What this example demonstrates

• A visitor who is not logged in can use the widget anonymously.
• A logged-in visitor can be welcomed and identified by the Guanta agent.
• The customer backend, not browser JavaScript, decides who the user is.
• The customer backend creates a short-lived, single-use identity token through the customer's Guanta tenant.
• The browser receives the one-time token but never receives the server credential.
• A conversation survives full-page navigation among Home, Account, and Orders.
• Login, logout, subsequent login, and account changes start new widget conversations.
• A user can explicitly select New chat without ending the application login session.
• The open/closed widget state follows normal navigation in one tab, but authentication changes and new tabs start closed.

The question “Who am I?” makes the identity boundary easy to see, but an AI response must not be used as an application authorization decision.

Authentication responsibilities

The customer application remains the identity provider for its own users:

Guanta authentication does not replace the customer's login system. It connects an already-authenticated customer session to a Guanta widget session.

Tenant, agent, widget, and credential relationship

Each customer integration is isolated inside a Guanta tenant:

Guanta tenant
└── Agent
    └── Widget interface
        ├── Public widget ID
        ├── Allowed customer origins
        └── Widget identity credentials
            ├── Customer production backend
            └── Customer staging backend

• Tenant: owns the agents, widget interfaces, credentials, tokens, and conversation data. GUANTA_BASE_URL selects this tenant runtime.
• Agent: defines the AI behavior used by the widget.
• Widget interface: exposes an agent through the web widget. It has its own public ID and allowed origins.
• Identity credential: authorizes one customer backend to create identity tokens for one widget interface.
• Identity token: carries one user assertion to one widget initialization. It is short-lived and can be consumed only once.
• Login context ID: an opaque value generated by the customer backend for one login session. It remains stable during navigation and changes after every login.
• Conversation resume token: an encrypted, Guanta-issued wrt_... value stored by the loader in first-party sessionStorage. It cannot resume an authenticated conversation without a fresh matching identity token.
• Visibility preference: a non-sensitive boolean stored separately in the same tab's sessionStorage. Guanta restores an open authenticated widget only after confirming that the same conversation resumed.

A credential created in one tenant cannot authenticate against another tenant. A credential for one widget interface cannot issue a usable identity token for a different widget.

It is normal to create multiple credentials for the same widget—for example, separate credentials for staging and production, or for two independently deployed customer backends. This makes rotation and revocation safer.

End-to-end flow

The token is created only when the widget is about to initialize. Creating it when the page first renders could allow it to expire before the visitor opens the widget.

Values supplied by Guanta

The environment-variable names below are conventions used by this example. A customer may use different names in their own application.

In the Guanta tenant UI:

1. Open Agents → Interfaces and select the widget interface.
2. Open its Playground and use Copy HTML to obtain the loader URL, integrity value, and widget public ID.
3. Open Widget Identity Credentials for the same interface.
4. Create a named credential for the customer backend and optionally set an expiry.
5. Confirm the tenant-user password and copy the complete credential when it is displayed.
6. Store the credential immediately in the customer application's secret manager. Guanta shows the complete value only once.

The widget's allowed origins must include the customer application's exact origin, including scheme and port where applicable.

Requirements

• PHP 8.2 or later
• PHP cURL extension
• A Guanta tenant with an active agent and widget interface
• The customer application's origin allowed on that widget interface
• A dedicated widget identity credential for that interface

Local setup

Copy the environment template:

cp .env.example .env

Configure the application and Guanta values:

APP_URL=http://127.0.0.1:8088
APP_SESSION_SECURE=false

GUANTA_BASE_URL=https://your-tenant.example
GUANTA_WIDGET_PUBLIC_ID=your-widget-public-id
GUANTA_WIDGET_IDENTITY_CREDENTIAL=wic_your-credential-id.your-secret
GUANTA_WIDGET_LOADER_INTEGRITY=sha384-your-published-integrity-value

GUANTA_WIDGET_IDENTITY_CREDENTIAL is sensitive. Keep it only in the ignored .env file for local development or in the deployment platform's secret store. Never place it in HTML, JavaScript, source control, screenshots, logs, analytics, or browser storage.

Start the local application:

./scripts/run.sh

Then open http://127.0.0.1:8088.

The PHP built-in server is for local demonstration only. Use a supported web server and PHP runtime for an internet-facing deployment.

Demo users

The committed CSV contains password hashes rather than plaintext passwords. The three local demo identities are:

The public user@example.com credentials are prefilled in the login form so a customer can test the authenticated flow immediately. All demo credentials are for this example only and must not be reused for real accounts.

For a real integration, replace the CSV authentication with the application's existing session, SSO, OAuth, OpenID Connect, Laravel, Symfony, or other authentication mechanism. The Guanta exchange begins only after that system has authenticated the request.

Standard widget embed

The page uses the ordinary Guanta widget loader with one additional attribute pointing to a customer-owned endpoint:

<script
  src="https://your-tenant.example/widget/embed-loader.v1.1.0.js"
  integrity="sha384-your-published-integrity-value"
  crossorigin="anonymous"
  data-public-id="your-widget-public-id"
  data-identity-token-url="/widget-identity.php"
  defer>
</script>

data-identity-token-url must resolve to the customer page's own origin. The loader calls it with POST when the widget initializes and includes the customer application's normal same-origin session cookie.

The endpoint must determine the current user and login context exclusively from the trusted server-side session. It must never accept external_user_id, full_name, or login_context_id from browser input.

When no application user is logged in, the endpoint returns anonymous state:

{"identity_token":""}

When a user is logged in, it returns the one-time token received from Guanta:

{"identity_token":"wit_<token-id>.<one-time-secret>"}

Responses containing identity information must use Cache-Control: no-store and should not be logged.

Identity-token API

The customer backend creates a token by calling the tenant-specific endpoint:

POST /api/v1/widget-identity-tokens HTTP/1.1
Host: your-tenant.example
Authorization: Bearer wic_<credential-id>.<secret>
Accept: application/json
Content-Type: application/json

{
  "widget_public_id": "your-widget-public-id",
  "external_user_id": "stable-customer-user-id",
  "full_name": "Customer User",
  "login_context_id": "opaque-id-for-this-login-session"
}

Successful response:

HTTP/1.1 201 Created
Cache-Control: no-store, private
Content-Type: application/json

{
  "identity_token": "wit_<token-id>.<one-time-secret>",
  "widget_public_id": "your-widget-public-id",
  "expires_at": "2026-08-14T12:00:00+00:00"
}

Field guidance:

• widget_public_id must match the widget interface to which the credential belongs.
• external_user_id should be the application's stable, non-secret identifier for the user. Prefer an immutable database ID or UUID over an email address that may change.
• full_name is the display name made available to the agent.
• login_context_id should be an opaque, unpredictable value generated on successful login, retained only in the customer's server-side session, and replaced on every later login. It enables secure conversation continuity and should not be a raw session cookie or session identifier.
• The credential is sent as a bearer credential only from the customer backend.

The API accepts an external user ID and login context ID of up to 128 characters and a full name of up to 191 characters. The login context is optional for backward compatibility, but authenticated conversations without it are intentionally non-resumable.

Typical error responses:

Treat any unsuccessful response as an authenticated initialization failure. Do not silently downgrade a logged-in visitor to anonymous, because that can hide configuration or availability problems.

How the PHP example implements it

1. public/index.php authenticates a demo user and stores the user's ID plus a newly generated opaque login context in the PHP session.
2. The widget loader calls public/widget-identity.php when the widget opens.
3. widget-identity.php reads the current user from the PHP session.
4. src/app.php sends the server-to-server request with the user assertion and login context to the tenant's identity-token API.
5. The same-origin endpoint returns the resulting one-time token to the widget loader.
6. The widget consumes the fresh token while creating or securely resuming the Guanta conversation session.
7. The loader stores only Guanta's opaque resume token and a boolean visibility preference in first-party sessionStorage, so conversation and open/closed state survive refreshes and full-page links within the same browser tab.

The example's identity endpoint additionally requires a POST request marked with X-Requested-With: GuantaWidget. This is a defense-in-depth check, not a replacement for session security, same-origin controls, or CSRF protections appropriate to the customer's application.

Conversation continuity requirements

Keeping the customer logged in is necessary, but it is not sufficient to restore a widget conversation. The same customer user may log out and later log in again, so Guanta must be able to distinguish one login session from the next. Otherwise, an old browser-held resume credential could incorrectly reopen a conversation from an earlier login.

The following pieces work together:

During ordinary full-page navigation:

1. The old page leaves Guanta's opaque resume token and visibility preference in the browser tab's sessionStorage.
2. The new page loads the same version 1.1 widget configuration.
3. The loader calls the customer-owned identity endpoint again.
4. The customer backend reads the current user and the unchanged login_context_id from its server-side session and requests a new one-time identity token.
5. The loader sends the fresh identity token and the previously issued opaque resume token to Guanta.
6. Guanta restores the conversation only after the widget, origin, external user, login context, active session, and expiry all match. It then returns a refreshed opaque resume token.
7. If Guanta confirms that the same conversation resumed, the loader also restores the tab's saved open/closed widget state.

The customer application does not need to save messages, copy a Guanta session ID between pages, or expose any conversation identifier in HTML. It should only preserve its own authenticated session and per-login context. Loader version 1.1 handles the Guanta resume credential automatically.

If the identity, login context, widget, origin, expiry, or stored token does not match, Guanta does not restore the earlier authenticated conversation. Login, logout, account switching, and subsequent login therefore begin with a closed, fresh widget conversation.

HTML templates in the example

The demo keeps presentation in the non-public html/ directory and application logic in src/. The three page templates share one layout and use small partial templates for authenticated and anonymous states. The public PHP files remain thin entry points.

Templates contain simple placeholders rather than executable PHP:

<h2>Welcome, {{full_name}}</h2>

src/template.php provides the deliberately small replace_tags() helper. Ordinary replacement values are HTML-escaped by default, so names, email addresses, validation messages, and other data cannot inject markup. Complete HTML fragments may be inserted only through the helper's separate trusted-fragment argument; this example uses that path exclusively for partials that were themselves rendered from files under html/.

The renderer rejects unknown placeholders, invalid placeholder names, non-scalar ordinary values, and template paths outside the html/ directory. Templates contain no PHP. This is intentionally not a general-purpose template engine; production applications should normally use their framework's established templating system and its escaping rules.

Adapting the flow to another backend

The server-side logic is framework-independent:

receive POST from the widget loader
load the current user from the authenticated application session

if there is no current user:
    return { "identity_token": "" }

load the opaque per-login context ID from the same server-side session
call the Guanta tenant API using the server-only credential
send widget_public_id, stable external_user_id, full_name, and login_context_id

if Guanta does not return 201:
    fail the authenticated widget initialization

return the one-time identity_token with no-store cache headers

the standard loader handles the opaque conversation resume token automatically

In a production framework, place the Guanta API call in a server-side service and protect the same-origin identity endpoint with the application's normal session middleware. Never let the browser submit or override the asserted user ID.

Login, logout, and account switching

An identity token is still short-lived and single-use. Conversation continuity comes from a separate Guanta resume token that is valid only alongside a fresh identity token asserting the same user and login context.

• Normal navigation and refresh: keep the same customer login context. Loader version 1.1 restores both conversation history and the previous open/closed state in that tab.
• Login: generate a new login context after authentication succeeds. Any earlier anonymous or authenticated resume token cannot match it, and the widget starts closed.
• Logout: clear the customer login context with the application session. The next widget initialization is anonymous, clears the stored authenticated resume token, and stays closed.
• Subsequent login or account switch: generate another new context even when the same user logs in again. Guanta starts a closed, new conversation.
• New chat: the widget clears the stored resume token and initializes a fresh conversation under the current login context while remaining open.
• New tab: browser-tab storage is separate, so the widget starts closed.
• Single-page applications: keep the widget mounted during route changes; when authentication state changes, recreate it or call the loader registry's resetConversation() method.

The example's Home, Account, and Orders links perform genuine full-page navigation so conversation resumption is visible and easy to test.

Security model

• The server credential is dedicated to widget identity issuance and scoped to one interface.
• Guanta stores credential secrets and one-time-token secrets as hashes.
• Identity tokens are short-lived, single-use, tenant-bound, and widget-bound.
• Resume tokens are encrypted, time-limited, widget-bound, origin-bound, user-bound, login-context-bound, and backed by an active server-side conversation.
• A resume token cannot replace the fresh identity assertion required for every authenticated page initialization.
• Saved visibility is only a boolean; the loader does not expose identity or login-context data to restore presentation state.
• The identity endpoint reads the user from the server-side session and never trusts browser-supplied identity fields.
• The loader requires the identity endpoint to be same-origin and sends cookies only to that origin.
• The example rotates the PHP session ID after login and logout and generates a new independent login context after every successful login.
• The example uses HttpOnly and SameSite session cookies and can enable Secure cookies through configuration.
• Failed authenticated identity issuance fails closed rather than silently creating an anonymous session.
• Passwords, password hashes, authentication cookies, and customer authorization data are never sent to Guanta.
• Only external_user_id, full_name, and the opaque login_context_id are asserted by this version of the API.
• Browser messages and prompts cannot create a trusted authenticated identity.

The trusted identity is context for the Guanta agent. It does not grant permissions inside the customer application, and agent output must not be treated as proof of authentication or authorization.

Credential lifecycle

Use separate credentials for separate customer environments or independently operated backends. Give each credential a descriptive name and an expiry where appropriate.

For rotation without interruption:

1. Create a second credential for the same widget interface.
2. Store and deploy the new credential to the customer backend.
3. Verify identity-token creation through the new credential.
4. Revoke the old credential in Guanta.

Regenerating an existing credential invalidates its previous secret immediately. Revoking a credential also prevents unconsumed tokens issued by that credential from being accepted.

Production checklist

• Serve both the customer application and Guanta endpoints over HTTPS.
• Set APP_SESSION_SECURE=true for this example when served over HTTPS.
• Store the widget identity credential in a secrets manager or protected runtime configuration.
• Keep .env files, credentials, identity tokens, and authenticated endpoint responses out of source control and logs.
• Allow only the required customer origins on the widget interface.
• Use separate staging and production credentials.
• Add appropriate application-level monitoring and alerting for failed identity exchanges.
• Apply rate limiting and CSRF protections appropriate to the customer identity endpoint.
• Generate a new opaque login context after every successful login and clear it on logout.
• Use loader version 1.1 or later for full-page conversation continuity.
• Verify navigation continuity and login/logout reset behavior.
• Verify that normal navigation preserves visibility, authentication boundaries close the widget, New chat stays open, and a new tab starts closed.
• Document credential ownership, expiry, rotation, and revocation procedures.
• Test both authenticated and anonymous behavior before release.

Troubleshooting

Relevant files

• public/index.php: Home entry point and login/logout UI
• public/account.php: separate full-page account route
• public/orders.php: separate full-page orders route
• public/widget-identity.php: same-origin browser endpoint that calls Guanta from the backend
• src/app.php: CSV authentication, PHP session, per-login context, configuration, and Guanta API client
• src/page.php: page actions, template selection, and standard widget configuration for the three demo pages
• src/template.php: escaped-by-default replace_tags() helper and template-path validation
• html/layout.html: shared document shell and navigation
• html/pages/: Home, Account, and Orders page templates
• html/partials/: authenticated, anonymous, setup, error, and widget-script fragments
• data/users.csv: demo identities with PHP password hashes
• scripts/run.sh: local PHP development server
• scripts/build-docs.sh: reproducibly renders the PNG diagram and standalone HTML guide
• docs/authentication-flow.mmd: Mermaid source for the authentication sequence diagram
• public/docs/authentication-flow.png: rendered diagram used by the README and HTML guide
• public/docs/guanta-logo.svg: local copy of the official Guanta logotype used by the demo and guide
• public/authentication-guide.html: generated standalone HTML version of this guide
• .env.example: non-secret configuration template
• tests/check.php: validation for demo users, login contexts, templates, escaping, and rendering safety

Verification

Validate the demo users and password hashes:

php tests/check.php

Rebuild the documentation artifacts after editing this README or the Mermaid source:

./scripts/build-docs.sh

For an end-to-end check:

1. Open the page while logged out and ask the widget “Who am I?”. It should state that no authenticated identity is available.
2. Log in with one of the separately supplied demo passwords.
3. Open the new widget session and ask “Who am I?”. It should answer with that user's configured full name.
4. Log out and confirm that a newly initialized widget no longer knows the previous identity.
5. Repeat with the second demo user to verify account isolation.

Getting help

If Guanta rejects a correctly formed request or the required tenant values are unavailable, contact your Guanta representative with the tenant name, widget interface name, timestamp, and HTTP status. Do not include credentials or identity-token values.