"}'
```
{% endtab %}
{% tab title="Embedded Chat widget" %}
Pass the signed-in user's token using `authToken` in React or `auth-token` in HTML.
The widget sends it with new chats, follow-up turns, and permission or credential requests. A headless instance supports `setAuthToken()` for refreshed tokens.
{% endtab %}
{% endtabs %}
#### Setup Identity Token
{% hint style="warning" %}
**Available on request.** Setup Identity Token is switched on only for the clients who have asked for it. If your widget doesn't show **Developer Mode**, it isn't enabled for you.
{% endhint %}
Setup Identity Token lets you try an agent as a specific signed-in person by pasting their token by hand. When a widget is created with `allowDeveloperMode`, its sidebar shows a **Developer Mode** switch. Switch it on and, for an agent with authentication enabled, a **Setup Identity Token** action appears under **Start New Chat**. Paste a token there to try the agent as that person.
* The token lasts for the session and is never stored.
* A token passed as `authToken` replaces one entered by hand.
* In the Agent Playground, Developer Mode is not available in production.
#### Use the token in MCP connections
Reference `$auth.token` in an MCP connection configuration where the downstream server expects a user credential. Qore replaces it with the verified token during the run.
> `$auth.token` works only in MCP connection configurations. Skills and agent instructions cannot access it.
{% hint style="info" %}
If a request has no token, `$auth.token` resolves to an empty value. The downstream server receives an anonymous request.
{% endhint %}
Use `$auth.token` like the `$secret.` and `$agent.` values described in [Secrets & Variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables.md). Ensure every caller sends a token when the downstream system requires a signed-in user.
### Request outcomes and token security
| Authentication | Token | Result |
| ------------------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Off | Any, or none | The run proceeds. Qore ignores the token. |
| On | None | The run proceeds without `$auth.token`. |
| On | Valid | The run proceeds. `$auth.token` contains the token. |
| On | Invalid, or issued for another application or client | Rejected with `AGENT_AUTHENTICATION_FAILED`. |
| On | Expired Microsoft Entra ID token | Rejected with `TOKEN_EXPIRED`. |
| On | Expired Google token | Rejected with `AGENT_AUTHENTICATION_FAILED`. Google reports expired and invalid tokens identically. |
| On, with incomplete provider details | Any token | Rejected with `AGENT_AUTHENTICATION_CONFIG_INVALID`. Update the agent configuration. |
| On, when Google is unavailable | Any token | Fails with `GOOGLE_IDENTITY_SERVICE_UNAVAILABLE` and HTTP `503`. Retry the request. |
If Microsoft Entra ID is unavailable, Qore rejects the request with `AGENT_AUTHENTICATION_FAILED`.
#### Token security
* Qore encrypts the token before queuing the run.
* Qore decrypts it only to verify the token.
* Qore never stores the raw token.
* Execution-status responses exclude the raw token.
* The embedded widget keeps the token only in session memory.
{% hint style="warning" %}
Send tokens only from your application's authenticated session. Do not accept tokens from URLs, form fields, or other user-controlled inputs.
{% endhint %}
***
{% columns %}
{% column width="83.33333333333334%" %}
Maintained by Abhishek Paul
AI-assisted, human-approved
{% endcolumn %}
{% column width="16.666666666666664%" %}
{% endcolumn %}
{% endcolumns %}
---
# 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.uptiq.ai/ai-workbench-qore/console/agent-builder/deploy/authentication-1.md?ask=&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.
