Authenticated conversation files

Authenticated conversation files is an opt-in setting for each project. Once enabled, new conversation uploads from both agents and customers are stored privately. This includes new files added to existing conversations. Possession of a file URL alone does not grant access. Agents must have permission to access the project and conversation. Customers must sign in to your application and use verified Gleap identity; they can access only customer-visible files in their own conversations. Internal notes and diagnostic captures remain agent-only.

This setting does not migrate or delete existing files. Public help-center and branding assets retain their existing behavior. Anonymous widget sessions and conversation share links do not grant access to protected files.

Before you enable the setting

For each project, prepare:

A customer application that authenticates its users and loads the compatible Gleap JavaScript SDK.
Server-side identity verification, using that project’s identity verification secret.
An HTTPS application entry URL that supports the login flow below.
Confirmation from Gleap that authenticated file access is available for your region and your deployed SDK integration.

The updated hosted JavaScript SDK supports this flow. If you bundle the npm package, pin an older script, or use a native/mobile SDK, confirm support with Gleap before activation. Identity verification support alone does not establish protected-file compatibility. Unsupported clients cannot display protected files.

1. Set up verified customer identity

After your backend authenticates a user, generate an HMAC-SHA256 hash from their stable user ID using the project’s identity verification secret. Derive the user ID from the authenticated server session, not an arbitrary user ID supplied by the browser.

// Server-side only. Supply the secret through your server's secret configuration.
const crypto = require('node:crypto');
const userId = String(authenticatedUser.id);
const userHash = crypto
  .createHmac('sha256', process.env.GLEAP_IDENTITY_SECRET)
  .update(userId)
  .digest('hex');

Return the user ID and hash to that user’s authenticated browser session. After initializing Gleap for the matching project, identify the customer:

// Values returned by your authenticated backend for the signed-in user.
Gleap.identify(userId, { name: user.name, email: user.email }, userHash);

Use the same stable user ID for existing customers so their conversation ownership remains consistent. Never put the identity verification secret in browser code or a URL. Call Gleap.clearIdentity() when the user signs out or before switching accounts. Deploy and verify this integration before turning on Enforce identity verification in Project settings → User identity. Enabling enforcement without valid hashes will cause existing identify calls to fail.

2. Choose the customer application URL

In Project settings → User identity → Conversation file access, the Customer application URL is your application’s HTTPS entry point, for example:

https://app.example.com/support

Choose a page that loads Gleap after login and can redirect signed-out visitors through your authentication flow. Do not use a corporate homepage, a file-storage URL, or a standalone identity-provider login page that cannot return to your Gleap-enabled application. Each project can have its own URL. When a customer follows a protected viewer link and selects Customer sign in, Gleap redirects them to this URL with a gleapFile query parameter:

https://app.example.com/support?gleapFile=0123456789abcdef01234567

The value identifies the requested file. It is not a password, access token, or authorization grant. Your application must keep gleapFile in the final page’s query string until the SDK has processed it after verified identification.

On arrival, read the gleapFile parameter. If the customer is already signed in, keep it on the page and initialize/identify with Gleap as usual.
If the customer is signed out, preserve the destination through your existing login or SSO return flow. Use your authentication framework’s supported return-state mechanism and validate return destinations as local or explicitly allowed application URLs.
After successful login, return to the Gleap-enabled page with the same query parameter, for example /support?gleapFile=0123456789abcdef01234567.
Load the compatible SDK and call verified Gleap.identify for the signed-in customer. Do not strip the parameter during an SPA route change or move it into a URL fragment.
The SDK checks the customer’s permission and opens the associated conversation. The customer can then view or download its permitted attachments.

You do not need to construct a signed file URL or handle the file-access token yourself. The SDK manages the separate file session. Opening the same link as a different customer does not grant access to the original customer’s conversation.

4. Activate each project

Coordinate activation with Gleap after the integration and regional rollout are ready. As a project administrator:

Open Project settings → User identity and confirm Enforce identity verification is enabled.
Under Conversation file access, enter the Customer application URL.
Turn on Require authenticated file access. The URL is saved together with this toggle; entering it alone does not save it.
Confirm that the setting was saved successfully. Refresh dashboard tabs before testing new uploads.

Repeat these steps for every project in scope. There is no organisation-wide activation switch. If activation fails because the regional rollout is not enabled, contact Gleap rather than changing your identity integration to work around it.

5. Verify your actual application

Use a test customer and conversation in each application:

Upload a new attachment as the customer and as an agent. Confirm both authorized sides can read the customer-visible files.
Follow the protected viewer link while signed out. Complete login and confirm the original gleapFile reaches the application and the correct conversation opens.
Repeat while already signed in. Test the full SSO flow, if used.
Open the file link in a clean browser and as a different customer. Neither should receive the protected bytes without the required identity and conversation permission.
Sign out and confirm new file requests no longer succeed under the old customer’s identity. Already downloaded bytes cannot be recalled.
Check email and external-channel attachment links. Recipients must be able to sign in to the configured application as the verified customer associated with that conversation; an email address or a shared link alone is insufficient.

Email and external-channel delivery use sign-in links instead of copies of protected files. Plan that customer experience before activation, especially for projects that currently support email-only or anonymous contacts.

Troubleshooting

Symptom	What to check
Login succeeds but no conversation opens	Preserve `gleapFile` on the final page; load the compatible SDK; call verified identify for the correct project and stable customer ID.
Customer cannot view a new file	Check the SDK integration, verified identity and conversation ownership. Agent-only notes and diagnostic captures are not customer-visible.
Identify calls fail after enabling verification	Generate the hash on your backend with the correct project’s secret and the exact user ID string passed to identify.
The application URL is not saved	Enter it before switching on authenticated file access and confirm the save succeeds. For later URL changes while protection is active, contact Gleap; do not toggle protection off simply to save a URL.
An older file still opens through its existing link	Existing files are unchanged. Historical migration or deletion is a separate operation.

Turning the setting off affects future uploads only. Previously protected files stay protected, and identity verification must remain enabled for their access.

Get Started

SDKs

Kai Code

Server-side event tracking

Guides

Before you enable the setting

1. Set up verified customer identity

2. Choose the customer application URL

4. Activate each project

5. Verify your actual application

Troubleshooting

​Before you enable the setting

​1. Set up verified customer identity

​2. Choose the customer application URL

​3. Preserve the requested file through login

​4. Activate each project

​5. Verify your actual application

​Troubleshooting

Before you enable the setting

1. Set up verified customer identity

2. Choose the customer application URL

3. Preserve the requested file through login

4. Activate each project

5. Verify your actual application

Troubleshooting