> ## Documentation Index
> Fetch the complete documentation index at: https://plain-docs-orca-916-agent-docs-restructure.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Identify signed-in customers in the chat widget by passing an email and an HMAC hash.

Authentication allows you to identify who you're talking to and personalize replies using known account context.

* Route and prioritize requests more accurately based on known customer attributes.

* Prevent duplicate customer records and avoid exposing information to the wrong person.

* Improve security without adding a second login for the customer.

Whether you're embedding chat behind a login or offering open access on your marketing site, the right authentication method ensures customers are identified correctly and securely.

## Authentication options

By default, customers chatting with you will be anonymous. You can pass customer details, if you know them, in the `Plain.init` function call:

```js theme={null}
Plain.init({
  // ... Other options
  customerDetails: {
    fullName: 'John Doe', // Optional
    shortName: 'John', // Optional
    chatAvatarUrl: 'https://picsum.photos/32/32', // Optional
    externalId: 'your_internal_user_id', // Optional. Your system's ID for this customer
    tenantIdentifier: { tenantId: 'ten_01ABC' }, // Optional. Or { externalId: 'your_tenant_id' }
  },
});
```

You can also include an email address using the `email` field property in the `CustomerDetails` object. To ensure the email is verified, Plain requires an `emailHash`, which is a secure hash of the email address and a secret.

There are two ways to provide this hash. You can generate it yourself if the user is already authenticated in your product, or you can use Plain's built-in email verification flow. Both methods are outlined below.

## Manual email verification - when you already know the user's identity

Use this approach when the user is logged into your application and you already know their verified email address.

If the chat widget is embedded in an authenticated environment (such as a customer dashboard), you can securely associate the session with the correct customer in Plain.

### Steps

1. **Generate a secret**
   Go to the Chat settings page in Plain and generate a secret.

2. **Calculate the email hash on your backend**

```ts theme={null}
import * as crypto from 'node:crypto';

const secret = 'your_chat_secret_here';
const email = 'johndoe@example.com';
const hmac = crypto.createHmac('sha256', secret);
hmac.update(email);
const hash = hmac.digest('hex');
```

3. **Initialize the widget with both the email and hash**

```js theme={null}
const email = 'johndoe@example.com';
const emailHash = await fetchHashFromBackend(email);

Plain.init({
  customerDetails: {
    email,
    emailHash,
    // Optional: additional customer details
    fullName: 'John Doe',
    shortName: 'John',
    chatAvatarUrl: 'https://picsum.photos/32/32',
  },
});
```

Always calculate the email hash server-side to protect your secret.

Because the `emailHash` is treated as a bearer credential, it must be protected like any other authentication token. Leaking the hash, or the secret used to generate it, would allow unauthorised parties to impersonate the customer.

## Built-in email verification - when you don't know the user's identity

Use this method when you do not know who the user is and want to verify their identity before they can chat. This is ideal for public pages, such as marketing sites, or anywhere you don't manage authentication yourself.

Plain's built-in verification flow prompts users to verify their email before they can start chatting.

To enable this, set the `requireAuthentication` option to `true` when initializing the Plain widget:

```js theme={null}
Plain.init({
  requireAuthentication: true
});
```

When enabled:

* Users will be asked to enter their email address

* Plain sends them a one-time code via email

* After verification, they can start a conversation