Home
/
iOS
/
Identity Verification

Identity Verification

Identity verification helps to make sure that conversations between you and your users are kept private and that one user can't impersonate another. We strongly encourage all Intercom customers to set up and enable identity verification.

Enable Identity Verification

Get the iOS identity verification secret from your app settings and store it in a secure place on your app server.

Next toggle enforce identity verification to on.

Have you already released your app with the Intercom messenger in it?

If you have then enabling identity verification will stop old versions of your app communicating with Intercom. We recommend that you complete setting up identity verification and test that everything is working. Then turn off identity verification and release an update to your app. This update will be sending user hashes to Intercom but not enforcing it. Once you are happy with the number of users on versions of your app sending the user hash you can come back and toggle identity verification on which will then start enforcing it for all versions of your app.

Returning the HMAC Digest from your App Server's Authentication Call

Your app server authentication code needs to be modified so that is uses the Intercom iOS API Secret to create a HMAC digest (hash based message authentication code) from the user id or email address for that user. Then it returns the HMAC digest to your iOS app. Note that identity verification does not apply to unidentified users, for whom you do not have a user id or email address.

The HMAC is computed as a SHA-256 digest as follows:

OpenSSL::HMAC.hexdigest('sha256', api_key.secret, user_id_or_email)

If you wish to generate a HMAC in a different programming language we have a comprehensive list here.

Set the User Hash in your iOS App

When your iOS app initializes Intercom if the user is identified (i.e., you have a user id or email address), pass in a String of the HMAC returned from your server's authentication call. This should be called before any registration calls:

  1. objectivec
  2. swift
[Intercom setUserHash:"your_hmac_of_user_id_or_email"];

The Intercom API Auth Server uses its copy of the iOS API Secret to recreate the HMAC digest from the user_id or email. If it matches with the supplied HMAC digest, we can be sure that this request is coming from your app server and the API Auth Server issues an access token to the iOS messenger.

If the HMAC fails to verify, the API Auth Server responds with a 401.

If you send both email and user_id values in your integration, you need to calculate the HMAC on the user_id value.

Sending an HMAC derived from the email will fail with a 401 if a user_id is provided

Troubleshooting

  • You must use the exact iOS Secret Key that we provide you within the code. Making up your own won't work. Note: Don't confuse this with your app_id.
  • Make sure you are using the iOS Secret Key, not the Android or web one they are not the same.
  • The user data passed to your server must be either the user_id or email for that Intercom user. If you supply both user_id and email, calculate the HMAC based on the user_id value
  • Do not forget that identity verification needs to be activated (and configured) separately in your development/test and production apps.