Secure user authentication

When you install Pavior on your site, you have the option to provide an email or id to identify the user. By default, this identifies the user, but it does not authenticate them. We have no way of knowing if that is their real id, or if they simply spoofed their identity by editing the javascript on your page. The same goes for any time they provide their email voluntarily, for example, by filling in the email field in a form.

Any user that has been authenticated in the past is placed in the signup universe. Users that have been identified but not authenticated will be leads. Learn more about user universes.

Any messages you receive from unauthenticated users will show their id, but also a warning symbol (⚠️) below the message. You should not send any sensitive information to unauthenticated users! Assume it may be an impersonator.

Pavior has a way for you to authenticate the user so that you can trust you are really communicating with them. For example, if they long into your website, you likely want Pavior to know that they are logged in so that if they ask a question about their account, you know that it's really them.

Note: the rest of the article is technical. You will need a developer to configure your chat for secure authentication. Please point them to this article.

Secure authentication using HMAC

In order to authenticate the user, Pavior uses hash-based message authentication codes (HMACs). When initializing Pavior, simply pass an hmac field. The hmac field should be the id (or the email if no id is provided) signed by your API key using sha256. Make sure both the api key and the id or email are encoded using utf8.

For example, if your API key is ladygaga and the user's email is user@example.com, with no id provided, you would call init as follows:

Pavior('init', {
  'teamVanityId': 'YOUR_TEAM_ID',
  'doChat': true,
  'doTimeTravel': true,
  'email': 'user@example.com',
  'hmac': 'ca4e0d714668828ecce7440675f0e520163747de2654cf74a53ca14b9db59832',
})

The python code that generated that hmac was:

import hmac
import hashlib
print(hmac.new('ladygaga'.encode('utf8'), 'user@example.com'.encode('utf8'), hashlib.sha256).hexdigest())

IMPORTANT: Make sure the hmac is calculated on a server that you trust, and then sent to the client. Your API key is a secret, it must never be sent to the client.

Secure authentication using domain whitelists

In some cases, you will want to use the authentication from your main domain on a secondary domain. For example, let's say:

1. Your primary domain is example.com, this is where your users log in
2. Your help center is at example.zendesk.com

You can let your help center "borrow" the authentication from your main website by using a domain whitelist. This will allow users to stay logged into the Pavior chat bubble as they navigate to your help center. To set up a domain whitelist, you need to do the following:

1. Add the third party to your domain whitelist by going to [MDX CODE]. Enter example.zendesk.com on its own line in the Shared Authentication Domains textbox.
2. In your init call, add the shareAuth parameter, pointing to your primary authentication domain:

   Pavior('init', {
     'teamVanityId': 'YOUR_TEAM_ID',
     'doChat': true,
     'doTimeTravel': true,
     'shareAuth': 'auth.example.com', // TODO: explain primary authentication domain
   })

If you need more information about authentication, check out our API reference.