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

Optional: z. B. { "chatHistory": false }, um den Chat-Verlauf für diesen Link zu deaktivieren.

chatHistory boolean

systemPromptInsertion string

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

permissionFilter

Optional: Daten-/Berechtigungsfilter (gleiche Filter-DSL wie in der übrigen API).

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

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

chatHistory boolean

systemPromptInsertion string — OPTIONAL

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

permissionFilter — OPTIONAL

400

Ungültige Eingabedaten

Schema — OPTIONAL

message string

Fehlermeldung

code string

Fehlercode

issues object[] — OPTIONAL

Liste der Ursachen, die zum Fehler geführt haben

message string

401

Autorisierung nicht angegeben

Schema — OPTIONAL

message string

Fehlermeldung

code string

Fehlercode

issues object[] — OPTIONAL

Liste der Ursachen, die zum Fehler geführt haben

message string

403

Unzureichende Berechtigung

Schema — OPTIONAL

message string

Fehlermeldung

code string

Fehlercode

issues object[] — OPTIONAL

Liste der Ursachen, die zum Fehler geführt haben

message string

500

Interner Serverfehler

Schema — OPTIONAL

message string

Fehlermeldung

code string

Fehlercode

issues object[] — OPTIONAL

Liste der Ursachen, die zum Fehler geführt haben

message string