Enhanced Identity Verification (EIV) is a way to be sure you and only you are reporting usage and engaging with each specific contact.
To enable EIV there are two steps - and they should be done in this order:
- You need to supply two hashed-based message authentication codes (HMACs) when communicating with ChurnZero; one for the accountExternalId and one for the contactExternalId
If you are integrated with the ChurnZero HTTP API these need to be supplied for each api request. Here is an example for doing a HTTP POST of JSON:
POST /i HTTP/1.1
Host: https://analytics.churnzero.net
Content-Type: application/json
Cache-Control: no-cache
{
"appKey": "{appKey}",
"accountExternalId": "{accountExternalId}",
"contactExternalId": "{contactExternalId}",
"accountExternalIdHash": "{accountExternalId}",
"contactExternalIdHash": "{contactExternalId}",
"action": "...",
}
|
ChurnZero.push(['setContact', 'accountExternalId','contactExternalId', 'hashedAccountExternalId', 'hashedExternalContactId']) |
- An administrator needs to sign into ChurnZero and provide the secret token your app will be using to generate the hashed-based message authentication codes (HMACs) . This can be done in the General Settings under the Admin section.
Keep Track of your Secret Token!It is vitally important to keep your secret token a secret. We understand mistakes happen though so if you ever need to change your secret token simply have an administrator login and enter the new token. Additionally, if you ever turn OFF EIV and then turn it back ON, your previous secret token will NOT be remembered. |
How does EIV help me stay secure?
EIV works by maintaining a private token that ChurnZero can use in combination with accountExternalId and contactExternalIds to verify the authenticity of the request. By hashing a combination of the secret token and the ids you can safely pass the resulting hash over the internet and only someone with the secret token will be able to verify that exact hash.
Here is an example:
Lets say you have a web application with a ChurnZero JavaScript integration, you have turned on EIV and set your secret token to "ThisIsNotASuperSecretToken". Now lets also assume you have an account called Pets with two contacts: Charles Barkly and Sazzles LeCat.
When Charles Barkly signs into your application you call set contact with their accountExternalId, contactExternalId, hashed accountExternalId, and hashed contactExternalId
JavaScript
ChurnZero.push(['setContact','pets_acct', 'cbarkly@petaccount.com','d7c8d96d40758cf5b42a3495216f0cc133573e089d5a95b |
JavaScript
ChurnZero.push(['setContact','pets_acct', 'slecat@petaccount.com','d7c8d96d40758cf5b42a3495216f0cc133573e089d5a95bf |
If you compare that to the call made for Charles Barkly you will notice the accountExternalId hashes are the same and this makes sense as the input was the same but the contactExternalId hashes are unique because one was
'ThisIsNotASuperSecretToken'+'cbarkly@petaccount.com' and the other was 'ThisIsNotASuperSecretToken'+'slecat@petaccount.com'
Looking for specifics on generating HMACs?
Checkout our dedicated article here "How do I generate HMACs?".
Comments
0 comments
Article is closed for comments.