User Authentication

The User Authentication extension lets your agent verify who a user is before granting access to private data. When a user asks for something that requires identification (e.g., “show me my orders”), the agent automatically asks for credentials and verifies them through your webhook.

Why use authentication?

Without authentication, your agent can only provide public information. With it enabled, your agent can:

• Show a user’s orders, invoices, or account details
• Perform actions on behalf of the user (cancel subscriptions, update settings)
• Personalize responses based on verified identity

How it works

On WebChat

1. A user asks for protected information (e.g., “meus pedidos”).
2. The agent recognizes the trigger requires authentication.
3. A login form appears in the chat (email + password, or your custom fields).
4. The user submits credentials.
5. SynapsAI verifies them via your webhook.
6. On success, the agent executes the action and shows the result.

On WhatsApp and Instagram

1. A user asks for protected information.
2. The agent asks for an identifier in the conversation (e.g., CPF or document ID).
3. The user replies with their identifier.
4. SynapsAI verifies it via your webhook.
5. If additional verification is needed, the agent presents a challenge (e.g., “confirm one of your registered phones”).
6. On success, the agent executes the action.

Note

On messaging channels, password fields are never collected because user input is visible. The agent uses document-based or phone-based verification instead.

Setting up

1. Enable the extension

1. Go to your agent’s Extensions page.
2. Find User Authentication in the Explore tab.
3. Click to open the configuration page.

2. Configure your webhook

Field	Description
Webhook URL	The endpoint SynapsAI calls to verify credentials. Must return JSON.
Webhook Secret (optional)	If set, SynapsAI signs requests with HMAC-SHA256 so you can verify authenticity.
Auth Mode	EAGER (prompt login immediately) or LAZY (only when a protected trigger is called).

Tip

Use LAZY mode for most setups. The agent only asks for credentials when the user actually requests protected data — better user experience.

3. Configure login form fields

Define which fields appear in the WebChat login form:

Field	Type	Example
Email	EMAIL	email input with validation
Password	PASSWORD	masked input (WebChat only)
Document ID	DOCUMENT_ID	CPF, SSN, or other national ID
Phone	PHONE	phone number input
Text	TEXT	any free-text field

You can also configure separate fields for messaging channels (WhatsApp/Instagram). Only safe types are allowed on messaging: TEXT, EMAIL, PHONE, DOCUMENT_ID.

4. Connect triggers to authentication

For a trigger to require authentication, configure it with:

• Auth type: Set to “User Session” in the trigger’s settings panel.
• Channel scope: Choose which channels can use this trigger.

When a user invokes an authenticated trigger, the agent automatically starts the login flow before executing the action.

Channel scope

Triggers can be scoped to specific channels. This is useful because:

• WebChat triggers can use Bearer tokens for API calls (the token from your webhook’s metadata.token field).
• Messaging triggers use identity injection — your user’s verified fields (like documentId) are inserted into the API URL.

Channel scope	Auth method	Best for
WebChat Only	Token-based (Bearer header)	APIs that accept JWT/session tokens
WhatsApp + Instagram	Identity-based (document in URL)	APIs that identify users by document/phone
All Channels	Depends on channel	General-purpose triggers

Caution

A trigger scoped to “WebChat Only” will not appear for WhatsApp users (and vice versa). If you need the same action on both channels, create two triggers — one per auth pattern.

What your webhook returns

Your webhook controls the authentication flow by returning one of three responses:

Response	When to use	What happens
Verified	Credentials are valid	Agent proceeds with the protected action
Challenge	Need additional step (OTP, phone confirmation)	Agent presents the challenge to the user
Failure	Credentials are invalid	Agent tells the user and may allow retries

On success, you can return:

• identity — fields the agent can use (name, email, role, etc.)
• metadata — private data like tokens (not shown to the user, used for API calls)

Example: “Show my orders” flow

1. Admin creates a trigger named “List Orders” with:

   • Auth type: User Session
   • Channel scope: WebChat Only
   • API endpoint: GET https://your-api.com/orders (with Bearer token)

2. Admin creates their webhook that:

   • Validates email + password against their user database
   • Returns { verified: true, metadata: { token: "jwt-for-orders-api" } }

3. End-user on WebChat types: “show me my orders”

4. Agent shows login form → user logs in → webhook verifies → agent calls orders API with token → shows results

Security best practices

• Always verify the HMAC signature (X-Synapsai-Signature header) in your webhook
• Use short-lived tokens in metadata (5–15 minutes)
• Never return sensitive data in identity — only what the agent needs for personalization
• Set challenge TTLs (3–5 minutes) to prevent replay attacks
• Use HTTPS for your webhook URL

Next steps

• Auth Webhook Contract — Full request/response reference for building your webhook
• Node.js starter — Ready-to-deploy Lambda template
• Python starter — Ready-to-deploy Lambda template
• Triggers — Learn how to create triggers that use authentication