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.

---

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":

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:

{
  "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.