All Collections
Setup & Installation
Installation basics
Using Identity Verification (Secure mode)
Using Identity Verification (Secure mode)

Improve security and prevent impersonation by installing Chameleon with identity verification.

Pulkit Agrawal avatar
Written by Pulkit Agrawal
Updated over a week ago

Note: This feature is now fully available to new customers. However, for existing customers, to make sure migrating to this method goes smoothly, Please email us if you're interested in transitioning to Secure Identity Verification.


Identify Verification enforces two simple rules

  1. Requests to Chameleon must have only originated from your application.

  2. Data sent to Chameleon cannot be obtained by another party.

It works by providing a way for Chameleon to verify the authenticity of requests made to our APIs (via a digital signature).

Note: Although it is optional, we encourage all our customers to enable secure Identity Verification.

Identity Verification works by ensuring that the signature you generate (when sending data to Chameleon) can only have been generated by you.

The code snippet you install in your web app - and the user ID you send are not private. Therefore we provide you with a secret with which you generate a verification hash, which we check. Only you can generate this hash, which validates that no third-party is sending us a request.

Additionally, we ask that you include the current timestamp when the token was generated so that we can reject requests that are too old, or being replayed back to us, and so that we can rotate your key.

Your users' data will be more secure since one user cannot "act as" another.

It does not impact end-user experience or performance in any way. Your end-users will not notice that identity verification is on/off unless they attempt to download their or another user's data via browser console.

Identity Verification is turned on and enforced when the first verified request is received. This means that if the uid_hash being sent does not verify, Identity Verification will fail and not be enabled for your account.

Once we receive any secured data from any page where your account's Chameleon token is used, all un-verified data (sent without the signature) will be ignored by Chameleon. This means that users identified without the verification hash will not see any Chameleon Experiences until they are securely identified.

You cannot turn off Identity Verification once you have started sending us secure data. Contact us if you need assistance.

If you are installing Chameleon for the first time and you're doing it manually with JavaScript, then we strongly recommend you use this method from the beginning.

If you are making a switch from sending unsecured data to secured data, then we recommend deploying this change to production first, to enable a smooth roll-out to your users.

An alternative path is to deploy to your staging environment in off-hours and then to production as soon as possible. During the period between first verification on staging and verification on production, no Chameleon Experiences will be shown to end-users in your production environment.

Note: Once you enable Identity Verification, all REST API requests must use your Secret API key found on this page and not your account token (identifier in the installed Chameleon code snippet). Any requests using your account token will be ignored (401 error response).


To do this, visit the Chameleon installation page in your web dashboard. This is only currently available to those installing via JS, so select this installation method:

Note: You cannot turn off Identity Verification once you have started sending us secure data. Contact us if you need assistance.

Below the code snippet, you will see the Identity Verification section where you can find your secret key. Use this key is used to generate SHA256 HAMC signature to send alongside the User ID. To make sure the deployment goes smoothly please use out Test signature button to check.

We have provided examples of how to do this for a range of languages, including Javascript, Ruby, Python, and others. You can find them in this Github repo.

⚠️ This key should not be shared with anyone, please add as an environment variable on the backend responsible for generating this hash. If a third-party gains access to this key, this secure method would be compromised. If needed, contact us to rotate your secret.

Add the uid_hash into the call to chmln.identify.

When using plain JavaScript:

chmln.identify(USER_ID, { uid_hash: USER_ID_HASH_FROM_BACKEND });

When using Twilio Segment:

// Send uid_hash *only* to Chameleon
analytics.identify(USER_ID, OPTIONS, { Chameleon: { uid_hash: USER_ID_HASH_FROM_BACKEND } });

You can test any domain you have installed Chameleon on and verify that secure data is being received. You can do so from the Installation section of your Chameleon Dashboard.

Any unverified requests made after the verification is enabled will return a 401 error HTTP response.

Note: If you install Chameleon on a domain that's different from your email domain, it will be automatically disabled, and you should manually enable it in your Environments. The same goes for new subdomains that you add to already-enabled domains. This is to ensure better security and that no malicious domains get added to your account.

Upon receiving your first verified request, verification is turned on and enforced.

You cannot turn off Identity Verification once you have started sending us secure data. Contact us if you need assistance.

Short answer is yes. Longer answer is that because your backend generates this signature, when you login as a different user, your system will send a signature corresponding to the different user.

Yes! We're so glad you asked. We can generate a new key for you when you request it, and it'll show up on your installation page. We'll leave both keys enabled while you switch them, then contact us and we'll remove the old one.

  • Are you sending a User ID along with the uid_hash? If you just send the uid_hash without the uid or just the uid once verification is on, Identity Verification check will fail (401 HTTP error code)

  • Are you sending the current timestamp inside and outside the signature? The current timestamp is required to be transmitted at the end of the signature and to have also been part of the signature. Refer to the code samples for language-specific instructions. Without this timestamp, value signatures are valid in perpetuity.

  • Are you using the correct Identity Verification secret? You need to use the Verification key provided. This is different from the token in your installation code snippet or other API keys. Making up a key will also not work.

  • Is this the latest version of your code? If this is an older version of your app, or your JavaScript code is cached you might not be sending a uid_hash with your user data in which case the check might also fail.

👉 Still having trouble with Identity Verification? Please email us and we’ll be happy to take a look!

Find out more

Did this answer your question?