> 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/serve/choose-channel/web-chat/source-id-access.md).

# Chat Without Logging In Using a Contact Source ID

Let users who are already logged in to your website start chatting with their own user identifier (Source ID), without logging in again. The platform maps this identifier to a contact, and requests wi

When you embed Web Chat in your website, users are often already logged in to your site. This setting lets them start chatting directly with the user identifier from your system, without going through another login screen, while the public chat URL still blocks anonymous access.

MaiAgent calls this identifier the **Source ID**, and uses this name in both the administration interface and the embed script. When the platform receives a Source ID, it maps it to (or creates) a **contact**. That user's conversation history is associated with this contact.

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

Before this setting, you had two choices for login settings:

* Enable login: Users were still asked to log in again, even though the embedding site had already verified their identity.
* Disable login: Anyone could use the public chat URL anonymously.

With this setting enabled, you can achieve both goals: users with a Source ID and a valid signature can chat directly, while all visitors without them are redirected to the login 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>

Setting location: In the left menu, go to " <mark style="color:blue;">Customer Service Conversations > Chat Platforms</mark> ", select a website-type chat platform, and open the " <mark style="color:blue;">Login Settings</mark> " tab.

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

This toggle depends on the login settings. You must first select a source (MaiAgent／AD／Keycloak／LINE) under " <mark style="color:blue;">Login Source</mark> ". Until you select one, the toggle is unavailable and the interface 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 Login Settings tab, with this toggle disabled by default</p></figcaption></figure>

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

Enable " <mark style="color:blue;">Allow embedded clients to chat without logging in using Source ID</mark> ". The verification method, signing secret, and integration examples appear only after you enable it.

<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 settings section shown after enabling the toggle; the verification method defaults to "Require signature verification"</p></figcaption></figure>

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

| Verification method                                                           | Description                                                                                                                                                                                                 | Use case                            |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| <mark style="color:blue;">Require signature verification</mark> (recommended) | The embedded client must include a signature calculated by your backend. Access is granted only after verification succeeds. Only a server holding the secret can start a conversation on behalf of a user. | Production environments             |
| <mark style="color:blue;">Source ID only</mark>                               | No signature is verified; access is granted when a Source ID is provided.                                                                                                                                   | Testing or closed internal networks |

{% hint style="danger" %}
When you select "Source ID only", the Source ID acts as an access pass. If your Source IDs are guessable values such as email addresses, student IDs, or employee IDs, others can impersonate those users to chat and read their conversation history. For scenarios that require verified identities, use signature mode or AD／Keycloak／MaiAgent login instead.
{% 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 you select signature mode and save the settings, the platform generates a signing secret. In the secret field, 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 share it with your engineer
* Click " <mark style="color:blue;">Regenerate</mark> " to issue a new secret

{% hint style="warning" %}
Store the secret in an environment variable on your server. Never put it in frontend code. Regenerating the secret immediately invalidates the old one. Update your backend at the same time, or all signature verification attempts 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, signature validity period, integration examples, and behavior preview</p></figcaption></figure>

{% hint style="info" %}
The validity period limits "how long this signature can be used to start a conversation", rather than how long the conversation lasts. Once a user has authenticated, they can chat normally and will not be logged out after 5 minutes.
{% endhint %}

## <mark style="color:blue;">3. How your engineer integrates it</mark> <a href="#integration" id="integration"></a>

The " <mark style="color:blue;">Integration Examples</mark> " section in the administration interface includes this chat platform's identifier, so the examples can be copied and used directly. For complete parameter descriptions, verification rules, and troubleshooting, ask your engineer to refer to [Web Chat Embedding 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, "{chat platform identifier}.{Source ID}.{timestamp}")`, passed as a hex string. The timestamp is in Unix seconds (UTC), generated by your backend.

{% 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 the values to the embed script on the frontend <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 for every visit**: Each signature can be used successfully only once. The embedded client must not cache signatures.
* **Calculate signatures on the backend**: Once the secret appears in frontend code, it is effectively public.
* **Keep clocks accurate**: The system allows 60 seconds of clock skew. Timestamps outside this range are rejected.
* **Use the correct chat platform identifier**: The signature includes the chat platform identifier. A signature calculated with another chat platform's identifier will not pass verification.

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

| Incoming request                                             | Result                                                  |
| ------------------------------------------------------------ | ------------------------------------------------------- |
| Includes Source ID ＋ valid signature                         | Starts chatting directly without a login screen         |
| Includes Source ID with an invalid or expired signature      | Rejected                                                |
| Reuses the same signature                                    | First use succeeds; second use is rejected              |
| No Source ID (including directly opening the public URL)     | Redirected to the login page                            |
| Verification method is "Source ID only" ＋ includes Source ID | Starts chatting directly without signature verification |
| This toggle is disabled                                      | Retains the original login settings behavior            |

{% hint style="info" %}
All rejection scenarios return the same external response, without revealing the reason for failure or whether a particular Source ID exists. The reason appears only in the signature verification failure log in the administration interface.
{% endhint %}

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

If you encounter integration issues, click " <mark style="color:blue;">View Signature Verification Failure Log</mark> " in the settings section to see recent failures, so your engineer can troubleshoot independently. The log does not contain secrets or full 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 causes                                                                                                                |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| Signature expired                          | Server clock skew, or the embedded client cached a signature                                                                 |
| Timestamp exceeds the allowed future range | Server clock is more than 60 seconds ahead                                                                                   |
| Signature mismatch (secrets may differ)    | The backend secret differs from the one in the administration interface, or the signature string was constructed incorrectly |
| Missing timestamp or signature             | The embedded client did not provide `ts` or `sig`                                                                            |
| Signature already used                     | The same signature was sent a second time                                                                                    |
| Replay prevention cache unavailable        | A temporary platform issue; the system rejects access rather than granting it                                                |
| Source ID maps to multiple contacts        | Duplicate contact records with the same Source ID exist on this chat platform                                                |

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

<details>

<summary>Will the user's conversation end when the signature expires?</summary>

No. The validity period only limits "how long this signature can be exchanged for an identity". Once the user has authenticated, the conversation duration follows Web Chat's existing mechanisms and is unaffected by the signature validity period.

</details>

<details>

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

Within a single chat platform, one Source ID maps to only one contact. If the same Source ID is used across multiple chat platforms, each platform has its own contact, with separate conversation histories.

</details>

<details>

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

This setting is disabled by default, so existing chat platforms retain their behavior. If you enable it and select signature mode, requests without `ts` and `sig` will be redirected to the login page. Confirm with your engineer that the embedded client has been updated before enabling it.

</details>

<details>

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

Users who have already authenticated can continue their current conversation. You control the issuance of signatures: stop issuing new signatures after a user logs out, and they will no longer be able to authenticate again. If you need access to expire immediately on logout, contact us so we can assess an appropriate approach.

</details>

<details>

<summary>Will AI tool calls include the login credentials of a user who enters with a Source ID?</summary>

No. "[Use the Keycloak login identity for tool calls](/maiagent-user-guide/en/serve/choose-channel/web-chat.md#keycloak-token-passthrough)" applies only to visitors who actually log in with Keycloak. The identity is determined by the organization member bound when the conversation is created, rather than the Source ID provided by the embedded client, so a Source ID cannot be used to impersonate someone else's credentials. If your tools need to identify users, use Keycloak login with that feature, or configure [MCP credentials](/maiagent-user-guide/en/build/tools/setup-contacts-mcp-credentials.md) for the contact.

</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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.