> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talqui.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedded Authentication (id-token)

## Introduction

**Embedded Authentication** lets you run Talqui inside another application while keeping your users logged in — without asking them to sign in a second time. Instead of exposing the long-lived operator **JWT** to the browser (or passing it around in URLs), your backend mints a short-lived, single-use **id-token** and hands it to the Talqui app-web, which exchanges it for a real operator session.

This is the recommended flow whenever Talqui is embedded (iframe, webview, or a redirect from your own product) and the operator is already authenticated on the host side.

***

## Overview of the flow

1. **Mint the id-token (server-side).** Your backend calls the standard login endpoint with the operator's credentials **and** `grantType: "id-token"`. Instead of the operator JWT, the response contains a single-use `idToken`.
2. **Redirect the user.** Your backend redirects the browser to the Talqui app-web entry point, passing the id-token in the query string: `https://app.talqui.chat/initiate/authenticate/?id-token=<idToken>`.
3. **Exchange the id-token.** The app-web view reads the id-token, calls the exchange endpoint, and receives a real operator session (`{ operator, token }`).
4. **The operator is in.** The app-web stores the session, strips the id-token from the URL, and redirects the operator into their tenant — already authenticated.

<Frame caption="Id Token Authentication Flow">
  ![Id Token Authentication Flow](https://kroki.io/plantuml/svg/eNqNUs9PwjAUvu-v-OJpRMbU4xIVPEliItEZz4_tORpHW9uHgIT_3TcQlJunpv1-vrbDKBRkMW8Tr6upjCcrOLt3UTDyHumUqne2de8MFNEdnxJLaj8WBpULnJE3O9ZoMj4l3QW3jByQ_rDJ-2zJ073nK0-TZJeX3XTSApPH5xIuNGTNF4lxNneeA4kLMW9dYyzSKnDNVgy1EedogsaUa88wdSZO-_YSdUKmjp1zgY0iZQf0wStvAsexLXB5dYHtMVuLFFBfRSuBOOTGGo0Qzmkhsy6u6ja3h5DrwWCQqOpfxQ-inFfVjGzDSI-lsP3tu2uxwUHYh-wZiXXCcJ96jTtKVJD3YF83wfjj8HgLbo6Xp4eTctpftcK2exJqA1O9xt_B6mSoD61f4RtM27Uf)
</Frame>

***

## The id-token

The id-token is a deliberately narrow credential:

* **Opaque and high-entropy** — a random, URL-safe string with no readable content.
* **Single-use** — it is consumed on the first exchange; any further attempt fails.
* **Short lived** — it expires automatically after **120 seconds** (2 minutes).
* **Earned** — it is only issued to a caller that already presented valid operator credentials.

Because it is single-use and expires in two minutes, an id-token that leaks (browser history, logs, referrer headers) has a very small window of usefulness and cannot be replayed.

***

## Step 1 — Mint the id-token

From your backend, call the login endpoint with `grantType: "id-token"`:

```bash theme={null}
curl --location 'https://api.talqui.chat/organization/operators/login' \
--header 'Content-Type: application/json' \
--data '{
  "operatorEmail": "operator@example.com",
  "operatorPassword": "<operator-password>",
  "grantType": "id-token"
}'
```

Response:

```json theme={null}
{
  "idToken": "s7f3...urlsafe...",
  "expiresIn": 120
}
```

Without `grantType`, this same endpoint keeps its default behaviour and returns the operator JWT `{ operator, token }`.

## Step 2 — Redirect the user to Talqui

Redirect the browser to the app-web authentication view, forwarding the id-token:

```
https://app.talqui.chat/initiate/authenticate/?id-token=<idToken>
```

Optionally, add a `redirect` query parameter to land the operator on a specific page after login (otherwise they go to their default tenant).

***

## Security best practices

* **Mint server-side only.** The `grantType: "id-token"` call requires operator credentials — keep it on your backend, never in the browser.
* **Redirect quickly.** The id-token lives for 120 seconds; redirect the user well within that window.
* **Never reuse.** Treat the id-token as consumed the moment you redirect; request a fresh one for each entry.
* **The long-lived JWT never touches a URL.** Only the short-lived id-token travels in the query string; the real operator token is issued by the POST exchange and stored by the app.

For the standard (non-embedded) operator, plugin and plugin-connection methods, see [Authentication](/guides/introduction/authentication).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.