Zum Hauptinhalt springen

Assistant Access Link erstellen

Legt einen neuen Assistant Access Link an: opaque token, fertige Widget-url und den gespeicherten jwtPayload. Authentifizierung: gültige Session (Bearer). Es werden Bearbeitungsrechte auf den Ziel-Space (über spaceId) bzw. auf den Bot (über veraltetes botId) benötigt. Bei API-Key-Aufrufen wird ohne spaceId und ohne botId automatisch der Space des API-Keys verwendet.

Handbuch (Konzept, Begrenzungen, Ablauf): /docs/assistant-access-links

Request Body — REQUIRED
sub string

Optional: stabile Nutzer- oder Subjekt-ID aus eurem System (Standard-Claim sub). Ermöglicht Zuordnung von Chats/Sessions, Audit und Personalisierung, ohne dass die ID selbst das Secret ist.

email string

Optional: E-Mail im JWT.

botId integer

Possible values: -9007199254740991 ≤ value ≤ 9007199254740991

Veraltet: bitte spaceId verwenden. Ziel-Bot; der Server leitet daraus den Space ab.

exp number

JWT-Ablauf (exp) als Unix-Zeitstempel in Sekunden. Wenn gesetzt, hat Vorrang vor ttlSeconds.

loginUrl string

Possible values: 1 ≤ length ≤ 2000

Optional: Login- oder Rücksprung-URL (absolute URL oder Pfad ab /), z. B. für Portal-Redirects.

aud string

Optional: vorgesehener Empfänger des Tokens (Claim aud), z. B. eure App- oder API-Kennung. Hilft, dass der Link nur in der erwarteten Umgebung als gültig gilt.

iss string

Optional: Aussteller des Tokens (Claim iss), z. B. eure Auth-Domain oder Produktname. Ermöglicht es Verifizierern, die Quelle zu prüfen und Vertrauensketten zu dokumentieren.

context object
widget object
filter object
features object

Feature-Flags für diesen Link, z. B. { "chatHistory": false }.

chatHistory boolean
systemPromptInsertion string

Optional: Zusätzlicher Text, der beim Chat an den System-Prompt angehängt wird.

permissionFilter object

Daten-/Berechtigungsfilter (Filter-DSL). Schlüssel sind or | and | not | search oder ein Feldname mit Prädikat { eq, ne, gt, lt, gte, lte, in, like, tp }. Beispiel: { "mime": { "eq": "application/pdf" }, "partOfId": { "eq": null }, "search": "report" }. Kein verschachteltes fields-Wrapper.

or (circular)[]
and (circular)[]
not (circular)
search string

Substring on filenames and indexed metadata (not the main chunk-body search). In rag_search this complements top-level query: use query for what the chunk text says; use search here to narrow by file name/path/metadata. Never use placeholders like '.' or '*' for “all rows”; use stats/aggregations for counts.

spaceId uuid

Possible values: Value must match regular expression ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Ziel-Space für den Assistant Access Link (bevorzugt). Es wird eine gültige Session und Bearbeitungsrechte auf mindestens einen Bot in diesem Space benötigt. spaceId und botId schließen sich nicht aus: bei beidem muss der Bot in diesem Space liegen. Bei API-Key-Aufrufen wird ohne spaceId/botId automatisch der Key-Space verwendet.

ttlSeconds integer

Possible values: 60 ≤ value ≤ 2592000

Gültigkeitsdauer in Sekunden (60 … 30 Tage), nur relevant wenn exp fehlt. Standard ohne exp: 3600 (eine Stunde).

userInformation object

Optional: User-Informationen als Key-Value-Paare z.B. User ID, Name, ...

Responses
200

Opaque token, fertige url und kanonischer jwtPayload wie in der Datenbank gespeichert.

Schema — OPTIONAL
token string

Opaque Zugangstoken für die Widget-Route /widget/{token} und für POST /assistant-link/exchange mit linkToken.

url uri

Fertige Widget-URL ({baseUrl}/widget/{token}) zum Teilen oder Einbetten.

jwtPayload object

Kanonischer JWT-Payload inkl. spaceId und exp, wie er in der Datenbank gespeichert wird.

v number
sub string — OPTIONAL
email string — OPTIONAL
spaceId uuid

Possible values: Value must match regular expression ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

botId number — OPTIONAL
exp number
loginUrl string — OPTIONAL

Possible values: 1 ≤ length ≤ 2000

aud string — OPTIONAL
iss string — OPTIONAL
context object — OPTIONAL
widget object — OPTIONAL
filter object — OPTIONAL
features object — OPTIONAL

Feature-Flags für diesen Link, z. B. { "chatHistory": false }.

chatHistory boolean
systemPromptInsertion string — OPTIONAL

Optional: Zusätzlicher Text, der beim Chat an den System-Prompt angehängt wird.

permissionFilter object — OPTIONAL

Daten-/Berechtigungsfilter (Filter-DSL). Schlüssel sind or | and | not | search oder ein Feldname mit Prädikat { eq, ne, gt, lt, gte, lte, in, like, tp }. Beispiel: { "mime": { "eq": "application/pdf" }, "partOfId": { "eq": null }, "search": "report" }. Kein verschachteltes fields-Wrapper.

or (circular)[] — OPTIONAL
and (circular)[] — OPTIONAL
not (circular) — OPTIONAL
search string — OPTIONAL

Substring on filenames and indexed metadata (not the main chunk-body search). In rag_search this complements top-level query: use query for what the chunk text says; use search here to narrow by file name/path/metadata. Never use placeholders like '.' or '*' for “all rows”; use stats/aggregations for counts.

400

Invalid input data

Schema — OPTIONAL
message string

The error message

code string

The error code

issues object[] — OPTIONAL

An array of issues that were responsible for the error

message string
401

Authorization not provided

Schema — OPTIONAL
message string

The error message

code string

The error code

issues object[] — OPTIONAL

An array of issues that were responsible for the error

message string
403

Insufficient access

Schema — OPTIONAL
message string

The error message

code string

The error code

issues object[] — OPTIONAL

An array of issues that were responsible for the error

message string
500

Internal server error

Schema — OPTIONAL
message string

The error message

code string

The error code

issues object[] — OPTIONAL

An array of issues that were responsible for the error

message string