AtlasCustomer portalAPI DocumentationGo to Atlas
Help Center›Admin Setup (For Admins)›Installation›How to enable customer (user) authentication
Table of contents
  • Overview
  • Key Features
  • Key terms
  • How to enable customer authentication
  • Generate the user hash
  • Add the hash to the identify call
  • How to view or copy the secret key
  • How to turn off authentication
  • FAQs & Troubleshooting
  • Why does Atlas not recognize my customers after I enabled authentication?
  • Can I generate the user hash in the browser?
  • Where do I find my secret key?
  • Who can see the secret key?
  • Does this apply to visitors who are not logged in?

    • How to enable customer (user) authentication

    Last updated October 8, 2026

    Who can use this feature?
    Admins only.

    Overview

    Customer authentication makes Atlas verify the identity of every customer who contacts your team through the widget. Without it, anyone who knows a customer's user ID could pass it to Atlas and chat while pretending to be that customer. With authentication turned on, your system sends a unique digital signature (a user hash) alongside each user ID, and Atlas only accepts the identity when the signature matches.

    The user hash is created on your server with SHA-256, using the user's ID and your workspace's secret key. You turn authentication on and copy the secret key from App Configuration; your developers then generate the hash in your backend and pass it in the identify call.

    This is a global setup: an Admin enables it once for the workspace, and a developer adds the hash to your backend and identify code.

    Related articles:
    •  How to install Atlas on your website or app: Install the snippet and identify call first.
    •  JS SDK: Full identify call reference.

    Key Features

    • Identity verification: Atlas checks a signature sent with each user ID, so customers cannot be impersonated in chat.
    • Server-side signature: The user hash is generated with SHA-256 and your secret key on your backend, never in the browser.
    • Secret key management: Reveal, hide and copy the secret key from the Authentication page whenever your developers need it.
    • Copy confirmation: Atlas shows a "Copied Secret key to clipboard." notification when the key is copied.

    Key terms

    ComponentDescription
    User IDThe unique identifier of a customer in your system, passed to Atlas as userId in the identify call.
    Secret keyA private key for your workspace, shown on the Authentication page. Only your backend should know it.
    User hashThe signature your server creates by hashing the user ID with the secret key using HMAC SHA-256. It is passed to Atlas as userHash.
    Identify callwindow.Atlas.call("identify", {...}), the call that tells Atlas who the logged-in customer is.
    Important:
    Treat the secret key like a password. Never put it in front-end code or a public repository.

    How to enable customer authentication

    Before you start, install Atlas and add the identify call to your app. For instructions, please read: How to install Atlas on your website or app.

    1. Open the main menu and select  "App Configuration" .
    2. Expand "Getting Started" and select "Authentication". The path is  "App Configuration > Getting Started > Authentication" .
    3. Turn on the authentication toggle to enable verification.
    4. Click the "Show Password" (eye) icon to reveal your secret key. You can view the key this way at any time.
    5. Click the eye icon again ("Hide Password") to hide the key once you have checked it.
    6. Click the "Copy" icon to copy the secret key to your clipboard. Atlas confirms with the notification "Copied Secret key to clipboard."
    7. Give the key to your developers securely, so they can store it in your backend configuration (for example as an environment variable).

    Generate the user hash

    In your backend, generate the user hash for the logged-in user with HMAC SHA-256, using the secret key and the user ID. The examples read the secret key from a server-side setting named ATLAS_USER_HASH_KEY; use any name you like. Select your language:

    PythonNode.js / Next.js
    import hashlib
    import hmac
     
    def get_atlas_userhash(user_id):
        secret = config['ATLAS_USER_HASH_KEY']  # your secret key, stored server-side
        key = secret.encode('ascii')
        message = str(user_id).encode('ascii')
        return hmac.new(key, message, hashlib.sha256).hexdigest()
    import { createHmac } from "crypto";
     
    export const generateAtlasUserObject = (user) => {
      if (!user) {
        return {};
      }
      const atlasSecret = process.env.ATLAS_USER_HASH_KEY || "";
      const hmac = createHmac("sha256", atlasSecret);
      hmac.update(user.id);
      const userHash = hmac.digest("hex");
      return {
        userId: user.id,
        name: user.name,
        email: user.email,
        userHash,
      };
    };

    Add the hash to the identify call

    1. Pass the generated hash to the front end and add it to the identify call as userHash: window.Atlas.call("identify", { userId: user.id, name: user.name, email: user.email, userHash: user.atlasHash })
    2. Deploy your changes. Customer conversations are now verified: Atlas chat won't start for anyone trying to spoof a user.
    Important:
    •  Any language with an HMAC SHA-256 library works, for example Ruby. Use the same inputs: the secret key as the key and the user ID as the message, with a hex digest as output.
    •  Create the hash from the same ID you pass as userId, or the signature won't match.
    Warning:
    Turn on the toggle only when your backend already sends the user hash.

    How to view or copy the secret key

    1. Go to  "App Configuration > Getting Started > Authentication" .
    2. Click the eye icon to reveal the key, or click the "Copy" icon to copy it.
    3. Click the eye icon again to hide the key.

    How to turn off authentication

    1. Go to  "App Configuration > Getting Started > Authentication" .
    2. Turn off the authentication toggle.

    FAQs & Troubleshooting

    Why does Atlas not recognize my customers after I enabled authentication?

    Common causes:

    • The identify call does not include userHash.
    • The hash was generated from a different value than the userId passed in the identify call.
    • The backend uses an old or mistyped secret key. Copy the key again from the Authentication page.
    • The hash was not generated with HMAC SHA-256.

    Can I generate the user hash in the browser?

    No. Generating the hash in the browser would expose your secret key. Always generate it on your server.

    Where do I find my secret key?

    In  "App Configuration > Getting Started > Authentication" . Click the eye icon to view it or the "Copy" icon to copy it.

    Who can see the secret key?

    Anyone with access to  "App Configuration" , which is Admin-only. Share it only with the developers who maintain your backend.

    Does this apply to visitors who are not logged in?

    Authentication verifies customers you identify with a user ID. It does not apply to anonymous visitors who have not been identified.

    Was this article helpful?