> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/conversations/web-chat/source-id-access.md).

# Passwordless Conversations with Contact Source ID

Let users already signed in to your website chat directly with their user ID (Source ID), without signing in again. The platform maps this ID to a contact, and unsigned requests cannot impersonate ano

When Web Chat is embedded in your website, users are often already signed in. This setting lets them start a conversation with your system's user ID without another sign-in screen, while continuing to block anonymous access through the public conversation URL.

MaiAgent calls this ID the **Source ID**. After receiving it, the platform maps it to (or creates) a **contact** and associates the user's conversation history with that contact.

## <mark style="color:blue;">1. What This Setting Solves</mark> <a href="#what-it-solves" id="what-it-solves"></a>

Previously, sign-in settings required one of two options:

* Enable sign-in: users were asked to sign in again even though the embedded site had authenticated them.
* Disable sign-in: anyone could anonymously use the public conversation URL.

After enabling this setting, users with a Source ID and valid signature can chat directly, while all other visitors are redirected to the sign-in page.

{% hint style="info" %}
This setting is disabled by default. When disabled, all existing behavior remains unchanged.
{% endhint %}

## <mark style="color:blue;">2. Enable the Setting</mark> <a href="#enable" id="enable"></a>

Go to “<mark style="color:blue;">Customer Service Conversations > Integration Platforms</mark>” in the left menu, select a website integration platform, and open the “<mark style="color:blue;">Login Settings</mark>” tab.

### 1. Select a login source first <a href="#prerequisite" id="prerequisite"></a>

First select a “<mark style="color:blue;">Login Source</mark>” (MaiAgent, AD, Keycloak, or LINE). Until then, the toggle is unavailable and displays “<mark style="color:blue;">Please select a login source first</mark>.”

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0bed4d025474ad42bf838b7e9e00e78f90693425%2Fsourceid-01-default.png?alt=media" alt=""><figcaption><p>The toggle is disabled by default on the Login Settings tab</p></figcaption></figure>

### 2. Enable the toggle <a href="#toggle" id="toggle"></a>

Enable “<mark style="color:blue;">Allow embedded clients to start conversations without signing in by using a Source ID</mark>.” The verification method, signing secret, and integration examples then appear.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-95e715c203b5b89846e419419586baad4076301b%2Fsourceid-02-enabled-signature.png?alt=media" alt=""><figcaption><p>The expanded settings; “Require signature verification” is selected by default</p></figcaption></figure>

### 3. Select a verification method <a href="#verify-mode" id="verify-mode"></a>

| Verification method                                                           | Description                                                                                                                                      | Recommended use             |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
| <mark style="color:blue;">Require signature verification</mark> (recommended) | The embedded client must include a signature generated by your backend. Only a server holding the secret can initiate a conversation for a user. | Production                  |
| <mark style="color:blue;">Source ID only</mark>                               | No signature is verified; a Source ID grants access.                                                                                             | Testing or closed intranets |

{% hint style="danger" %}
With “Source ID only,” the Source ID is an access credential. If it is guessable, such as an email address, student number, or employee ID, someone could impersonate that user and read their history. Use signature mode when identity assurance is required, or use AD, Keycloak, or MaiAgent login.
{% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-8fa84f2e4965e66f8872be1997424f02b47e77c5%2Fsourceid-03-raw-mode-warning.png?alt=media" alt=""><figcaption><p>A red risk warning appears when “Source ID only” is selected</p></figcaption></figure>

### 4. Obtain the signing secret <a href="#signing-secret" id="signing-secret"></a>

After selecting signature mode and saving, the platform generates a signing secret. You can:

* Click “<mark style="color:blue;">Show</mark>” to view the full secret (masked by default)
* Click “<mark style="color:blue;">Copy</mark>” to provide it to your engineer
* Click “<mark style="color:blue;">Regenerate</mark>” to issue a new secret

{% hint style="warning" %}
Store the secret in a server environment variable. Never place it in frontend code. Regenerating it immediately invalidates the old secret; update your backend at the same time or every signature will fail.
{% endhint %}

### 5. Set the signature validity period <a href="#signature-ttl" id="signature-ttl"></a>

Choose 1, 5, or 15 minutes. The default is 5 minutes. Expired or previously used signatures are rejected.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-2e4eb936b04e8a0ffea6d1aa0dac6fa5b6ec0407%2Fsourceid-04-secret-ttl-snippets.png?alt=media" alt=""><figcaption><p>Signing secret, validity period, integration examples, and behavior preview</p></figcaption></figure>

{% hint style="info" %}
The validity period limits how long the signature can be used to open a conversation; it is not the conversation lifetime. Once identity is established, the user is not signed out after five minutes.
{% endhint %}

## <mark style="color:blue;">3. Integration Instructions for Engineers</mark> <a href="#integration" id="integration"></a>

The “<mark style="color:blue;">Integration Examples</mark>” section includes this platform's ID and can be copied directly. For complete parameters, rules, and troubleshooting, see [Web Chat Embed and SDK · Signature Verification](https://docs.maiagent.ai/tech/api-integration/web-chat-sdk#source-id-signature).

### 1. Calculate the signature on the backend <a href="#backend-signature" id="backend-signature"></a>

The signature is `HMAC-SHA256(secret, "{integration platform ID}.{Source ID}.{timestamp}")`, passed as a hex string. Your backend generates the Unix timestamp in seconds (UTC).

{% tabs %}
{% tab title="PHP" %}
{% code overflow="wrap" %}

```php
$ts  = time();
$sig = hash_hmac('sha256', "{$webChatId}.{$sourceId}.{$ts}", $SIGNING_SECRET);
```

{% endcode %}
{% endtab %}

{% tab title="Node" %}
{% code overflow="wrap" %}

```javascript
const ts = Math.floor(Date.now() / 1000);
const sig = crypto.createHmac('sha256', SIGNING_SECRET)
  .update(`${webChatId}.${sourceId}.${ts}`).digest('hex');
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code overflow="wrap" %}

```python
ts = int(time.time())
sig = hmac.new(SIGNING_SECRET.encode(),
  f"{web_chat_id}.{source_id}.{ts}".encode(), hashlib.sha256).hexdigest()
```

{% endcode %}
{% endtab %}
{% endtabs %}

### 2. Pass values to the frontend embed script <a href="#frontend-setup-auth" id="frontend-setup-auth"></a>

{% code overflow="wrap" %}

```javascript
window.MaiAgent.setupAuth({ sourceId, name, ts, sig });
```

{% endcode %}

### 3. Integration notes <a href="#integration-notes" id="integration-notes"></a>

* **Generate a new signature on every entry**: each signature can succeed only once. Do not cache it.
* **Calculate signatures on the backend**: exposing the secret in frontend code makes it public.
* **Keep the clock accurate**: the system permits 60 seconds of clock skew; timestamps outside this range are rejected.
* **Use the correct platform ID**: a signature calculated with another platform's ID will fail.

## <mark style="color:blue;">4. Behavior Reference</mark> <a href="#behavior" id="behavior"></a>

| Incoming request                                | Result                                                 |
| ----------------------------------------------- | ------------------------------------------------------ |
| Source ID + valid signature                     | Opens the conversation directly without a login screen |
| Source ID + invalid or expired signature        | Rejected                                               |
| The same signature is reused                    | First request succeeds; second is rejected             |
| No Source ID (including opening the public URL) | Redirected to the login page                           |
| “Source ID only” + Source ID                    | Opens directly without signature verification          |
| This toggle is disabled                         | Existing login behavior remains unchanged              |

{% hint style="info" %}
All rejection scenarios return the same external response. It reveals neither the reason nor whether a Source ID exists. Reasons appear only in the admin failure log.
{% endhint %}

## <mark style="color:blue;">5. Signature Verification Failure Log</mark> <a href="#verification-failures" id="verification-failures"></a>

If integration fails, click “<mark style="color:blue;">View Signature Verification Failure Log</mark>” in the settings to view recent failures. The log contains neither the secret nor complete signatures.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-97836892fb059355c1a832478e76d6795a3a1719%2Fsourceid-05-verification-failures.png?alt=media" alt=""><figcaption><p>The expanded signature verification failure log</p></figcaption></figure>

| Reason                                     | Common cause                                                                 |
| ------------------------------------------ | ---------------------------------------------------------------------------- |
| Signature expired                          | The server clock is offset, or the embedded client cached the signature      |
| Timestamp exceeds the allowed future range | The server clock is over 60 seconds fast                                     |
| Signature mismatch (secret may differ)     | The backend secret differs, or the signature string is assembled incorrectly |
| Missing timestamp or signature             | The embedded client omitted `ts` or `sig`                                    |
| Signature already used                     | The same signature was submitted twice                                       |
| Replay-prevention cache unavailable        | Temporary platform issue; the system rejects instead of allowing access      |
| Source ID maps to multiple contacts        | Duplicate contacts with the same Source ID exist on this platform            |

## <mark style="color:blue;">6. FAQ</mark> <a href="#faq" id="faq"></a>

<details>

<summary>Will the conversation be interrupted when the signature expires?</summary>

No. The validity period only limits how long the signature can establish an identity. Afterward, conversation lifetime follows the existing Web Chat mechanism.

</details>

<details>

<summary>Can one Source ID map to multiple contacts?</summary>

Within one platform, a Source ID maps to one contact. Across multiple platforms, each platform has its own contact and separate conversation history.

</details>

<details>

<summary>Will enabling this setting affect existing embeds?</summary>

It is disabled by default, so existing behavior remains unchanged. In signature mode, requests without `ts` and `sig` go to the login page. Confirm the embedded client is updated before enabling it.

</details>

<details>

<summary>Can users continue chatting after signing out of my website?</summary>

Users whose identity is already established can continue that conversation. After sign-out, stop issuing new signatures so they cannot establish identity again. If you require immediate invalidation on sign-out, contact us to evaluate an approach.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/conversations/web-chat/source-id-access.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.