Set up Identity Verification for web and mobile

Enhance your security and prevent impersonation by setting up Identity Verification.

Penny-Merelle avatar
Written by Penny-Merelle
Updated over a week ago

Setting up Identity Verification will require technical changes to your Intercom Messenger installation and requires access to server side code most of the time.


Set up Identity Verification on web

Step 1: Generate and send hashes for your users

First you need to start generating hashes for your users using your Identity Verification secret. Go to Settings > Security > Enforce identity on web and click on Add Identity Verification to your application to get started.

Then choose how you installed your Messenger (with code or with an integration).

Now you'll need to generate an HMAC on your server for each logged-in user and send it to Intercom. First, choose how you want to uniquely identify your users via User ID or Email.

If you choose to send both to Intercom, the User ID will take preference.

Then choose the server-side language or framework you're using to get your code to generate an HMAC for your app.

When sending your user hashes along with your user requests, you should include the identifier that was hashed. Here’s a sample request where the workspace created the hash on the user_id value.

 window.intercomSettings = {
api_base: "https://api-iam.intercom.io",
app_id: "tx2p130c",
user_id: "123", // User ID
user_hash:"INSERT_HMAC_VALUE_HERE"// HMAC using SHA-256 };

Step 2: Verify that your installation is working

Once you’ve set up Identity Verification in your code and started sending user_hashes for each user, check the installation is working as expected.

From Settings > Security > Enforce identity on web, open Test your installation and click on Check installation.

Ensure that you have dealt with all errors on all the domains in the list. These are all the domains from which we have received a ping.

You can also use our hash checker to verify that the user hash values you're sending over to Intercom are correct, ensuring that Identity Verification will work correctly. Here, you can verify what the expected user hash is based on user_id or email (if you're not using user_id's).

Step 3: Enforce Identity Verification

Once you’ve got your signed-in user installation set up with the correct user hash, you can click Finish setup and enforce Identity Verification.

If you’ve installed Intercom with the WordPress app, you can enable Identity Verification in your settings with no configuration needed. however only for a US hosted Intercom workspace. Wordpress is not available for EU hosted workspaces right now.

Important: All of your ping request must include user_hash for you to enforce Identity verification on web.

Set up identity verification for other platforms

It’s possible to install Identity Verification for other installation methods also. Please see:


Set up Identity Verification on your mobile app

Step 1:

First, select Enforce identity on iOS or Enforce identity on Android under Security in the Settings menu.

Step 2:

Retrieve the Identity Verification secret and store it in a secure place on your server.

You should not store the secret in your mobile app; your server should only send the user_hash to your mobile app.

Step 3:

Then, follow our mobile SDK guides for the platform you’re using:

Step 4:

Once you have tested that your Messenger is working as expected in your app, turn off Identity Verification and publish the new Identity Verification-enabled version on the App Store. When you reach a high level of adoption, toggle Identity Verification on, which will then start enforcing it for all versions of your app.

Enabling Identity Verification will stop old versions of your app communicating with Intercom if they don’t send a valid user_hash.


How to turn off Identity Verification

You can turn Identity Verification on or off at any time by navigating to Settings > Security > Enforce identity on web. This can be useful while you’re developing.

Your app will be unprotected while Identity Verification is turned off. This means one User of your app could attempt to impersonate another, and see their conversations or modify their data in Intercom.


How to rotate your Identity Verification secret

We can rotate your identity verification secrets for you from our end, this cannot be done from your own workspace. To perform this rotation we will need you to contact us directly and to do the following:

  1. Have you disable identity verification from within Intercom (individually for web, iOS or Android)

  2. We will then rotate the specific secret

  3. You will refresh the page to view the new secret

  4. You then will implement the new secret into your code to generate the proper user_hashes

  5. Lastly, you'll enable identity verification again

There will be no downtime, however, during the completion of steps 2-5 your users will be able to use the Messenger without identity verification enabled.

Find out more about Identity Verification or try our troubleshooting tips if you're experiencing issues with setup.


💡Tip

Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts


Did this answer your question?