Skip to main content
This document describes the widget authentication system that allows the AGO frontend to work correctly when embedded as a widget in third-party websites. The same authentication mechanism is also used by the SDK API for building custom chat interfaces.

​
Overview

The widget authentication system enables the AGO application to authenticate users automatically when running in embed mode (widget context) or via the SDK API, without requiring traditional login flows. This is achieved through:
  1. Anonymous user ID: A unique identifier for each end user, sent as the X-User-Anon-Id header (X-Widget-Id is the legacy name and still accepted)
  2. Allowed Domains: The request origin is validated against your allowed domains list
  3. JWT Token (Optional): For authenticated user sessions with custom claims
  4. Automatic User Creation: Backend automatically creates users for widget/SDK sessions

​
Usage

​
Embedding the Widget

​
Anonymous Access

For anonymous user sessions, no extra configuration is needed. The backend creates a unique user for each widget instance based on a generated user ID inside the widget iframe. To help identify users across sessions, we store this ID in localStorage under the key ago-widget-id. We can define in the admin, different permissions based on if the user is anonymous or authenticated via JWT.

​
Using JWT Authentication

For authenticated user sessions, you can provide a JWT token:
The JWT will be used in the widget and be sent with the Authorization: Bearer <token> header on all API requests.
Authentication Flow with JWT

Authentication Flow with JWT

Backend Configuration Widget authentication is configured through backend settings:
  • Widget allowed domains: The list of origins allowed to embed the widget and call the API
  • Widget JWT JWKS URL: Required for JWT authentication. This URL should point to your JSON Web Key Set (JWKS) endpoint that provides the public keys used to verify JWT signatures. Without this configuration, JWT authentication will not work.

​
API Request Flow

When the widget or SDK makes API requests, the following headers are sent:
X-Widget-Id is the legacy name for the X-User-Anon-Id header and is still accepted. On the SDK API, the X-User-Anon-Id header is optional when a JWT is sent: the user identity is then taken from the token’s sub claim, so Authorization: Bearer <jwt> alone is enough. The backend validates each request by:
  1. Validating the request origin against your allowed domains list
  2. Verifying the JWT signature if a token is provided (using your configured JWKS URL)
  3. Creating or retrieving a user based on the user ID or JWT claims

​
Security Considerations

​
Domain Restrictions

  • Add only the domains that should be allowed to embed the widget to the allowed domains list
  • The request origin is checked against your allowed domains list before a session is created

​
Troubleshooting

​
Common Issues

  1. Widget authentication fails
    • Check that origin is in allowed domains list
    • Ensure the X-User-Anon-Id (or legacy X-Widget-Id) header is present, or that a JWT is sent on the SDK API
  2. JWT validation fails
    • Verify JWT signature and expiration
    • Ensure public keys are configured in backend
    • Check JWT claims match expected format