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.
• Login, logout, and account changes do not share authenticated widget sessions.

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.

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.0.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 exclusively from the trusted server-side session. It must never accept external_user_id or full_name 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"
}

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.
• The credential is sent as a bearer credential only from the customer backend.

The current API accepts an external user ID of up to 128 characters and a full name of up to 191 characters. Both values are required.

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 only the user's ID 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 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 token while creating the Guanta conversation session.

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.

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": "" }

call the Guanta tenant API using the server-only credential
send widget_public_id, stable external_user_id, and full_name

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

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

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 initializes one widget session; it is not a permanent login token.

• Login: initialize a new widget session after the customer login completes.
• Logout: destroy or reload the current widget instance after clearing the customer session. A new widget session must be anonymous.
• Account switch: destroy or reload the widget before initializing it for the new user.
• Single-page applications: explicitly recreate the widget when authentication state changes rather than retaining the previous iframe or conversation session.

This example performs full-page navigation after login and logout, which naturally creates a fresh widget instance.

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.
• 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.
• 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 and full_name 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.
• Recreate the widget session on login, logout, and account switching.
• Document credential ownership, expiry, rotation, and revocation procedures.
• Test both authenticated and anonymous behavior before release.

Troubleshooting

Relevant files

• public/index.php: login/logout UI and standard widget embed
• public/widget-identity.php: same-origin browser endpoint that calls Guanta from the backend
• src/app.php: CSV authentication, PHP session, configuration, and Guanta API client
• 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 the demo CSV and password hashes

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.