End-User Authentication
Authenticate end users mid-conversation
End-user authentication is how an agent verifies who someone is, during a conversation. The Helvia Agents Platform supports two paths: validate a token the embedding site already supplies, or prompt the user to sign in mid-conversation. Either way, the verified claims become workflow inputs you can use to personalize answers, gate sensitive actions, or route conditionally.
How Authentication Works
Authentication is how you verify who the end user actually is. Once verified, the user's name, email, and other claims become variables the workflow can read for the rest of the session. There are two modes for authenticating end users. The mode is selected automatically, based on whether a valid pre-auth token arrives with the conversation.
A few behaviors keep the authentication experience smooth at runtime.
Prerequisites
The two modes have different prerequisites. Confirm the right pieces are in place before enabling either on a live agent.
Pre-Authenticated Tokens
No Workspace integration needed. The embedding site must already authenticate the user against an external identity provider, then deliver the token to Webchat via setTokens or customData.
Interactive Sign-In
This mode requires an OpenID integration to authenticate users with your identity provider. Set up the integration in Workspace > Integrations.
Configure Authentication for an Agent
Authentication is configured per agent under Designer > Privacy & Security > Authentication. The page has two independent sections:
Pre-authenticated tokens
Interactive OIDC sign-in
Configure at least one for the agent to authenticate users. Both can run side by side if your deployment needs them.

Using Identity in Workflows
Once a user is authenticated, their claims are exposed as workflow session variables under Auth.* and stay available for the rest of the session. Reference them in conditions, prompts, API calls, or any node that reads workflow variables, the same way you would reference any other user attribute.
The following workflow nodes work directly with this state and are what most workflows use to gate access:
The user's identity can also reach MCP servers the agent calls. Turn on token forwarding for a server, and it receives the user's access or ID token, so it can identify the user or act on their behalf. See the Tools page for setup.
The End-User Experience
The user-facing journey depends on which authentication path the agent takes:
Key Terms
OIDC
OpenID Connect, an identity-layer protocol built on OAuth 2.0. The standard used for interactive sign-in.
OpenID integration
A Workspace-level configuration that captures an identity provider's discovery URL and client credentials.
Identity provider
The external system that authenticates users and issues tokens, for example Microsoft Entra ID, Google, Okta, or Keycloak.
Claim
A single piece of identity information returned by the identity provider, such as name, email, or groups. Multiple claims together describe the user.
Token
A signed string the identity provider issues to represent an authenticated user. The platform verifies the signature before trusting any claims inside.
Pre-authenticated token
A token the embedding site already holds when the conversation starts, because the user is signed in upstream. The platform validates it without prompting for a fresh sign-in.
Audience (aud)
A claim inside the token that names who the token is meant for. The platform only accepts tokens whose aud matches a configured provider.
JWKS
JSON Web Key Set, the public keys the identity provider publishes so token signatures can be verified.
Embedding site
The web page or host context where the agent is loaded through Webchat. Examples: a SharePoint web part, an intranet portal, a public landing page.
Best Practices
Prefer pre-authenticated tokens when the host already authenticates: Skipping the sign-in button removes a step from the user journey and keeps the experience inside the embedding page's session
Use the Is Authenticated node for mid-flow re-checks: It is cheaper than re-prompting and handles token refresh transparently
Request only the claims you use: Add to Additional Claims what the workflow actually reads, since extras clutter your variables and make audits harder
Authenticate as late as possible: Place the Authenticate User node just before the first step that needs identity, so unauthenticated users can still reach steps that don't require it
Add a provider per embedding context: When the same agent runs in two host sites with different audiences, configure two pre-auth providers rather than one broad rule
Last updated

