Assistant Access Link¶

Ein Assistant Access Link ist ein kontrollierter Zugangslink zu einem Assistenten. Er ist sinnvoll, wenn Personen einen Assistenten nutzen sollen, ohne sich erst durch den normalen Arbeitsbereich klicken zu müssen.

Im Alltag ist das vor allem dann nützlich, wenn ein Assistent in eine Website, ein Portal oder einen klar abgegrenzten Prozess eingebunden werden soll.

Wann du ihn nutzen solltest¶

Ein Assistant Access Link passt besonders gut, wenn:

externe Personen direkt in einen bestimmten Assistenten geführt werden sollen
ein Assistent nur für einen klaren Anwendungsfall freigegeben werden soll
du die Nutzung bewusst begrenzen möchtest, zum Beispiel auf einen kurzen Zeitraum oder auf ausgewählte Funktionen
der Einstieg möglichst einfach sein soll, etwa aus einem Intranet, Kundenportal oder einer eingebetteten Oberfläche heraus

Was Empfänger mit dem Link sehen¶

Der Link öffnet direkt den vorgesehenen Assistenten. Empfänger müssen nicht erst den ganzen CLYE AI verstehen, sondern landen direkt im passenden Einstieg.

Je nach Einrichtung können sie dort:

direkt mit dem Assistenten chatten
nur einen begrenzten Funktionsumfang nutzen
auf einen bestimmten Zweck oder Kontext eingeschränkt arbeiten

Ein Assistant Access Link ist deshalb kein allgemeiner Zugang zum gesamten System, sondern ein gezielt freigegebener Einstieg.

Was du beim Erstellen festlegen solltest¶

Beim Einrichten solltest du vor allem diese Fragen klären:

Für wen ist der Link gedacht?
Wie lange soll er gültig sein?
Welche Funktionen sollen erlaubt sein?
Soll der Assistent mit einem klar begrenzten Kontext arbeiten?

Typische Begrenzungen sind:

nur vorübergehend gültig
keine oder nur ausgewählte Werkzeuge
keine oder eingeschränkte Upload-Möglichkeiten
kein Zugriff auf bestehende Chatverläufe

Je klarer du diese Punkte festlegst, desto sicherer und nachvollziehbarer bleibt die Nutzung.

Typischer Ablauf¶

Ein einfacher, praxistauglicher Ablauf sieht so aus:

Öffne die Einstellungen des passenden Assistenten oder Bereichs.
Erzeuge dort einen Assistant Access Link.
Lege Gültigkeit und erlaubte Funktionen fest.
Teile den Link nur mit dem vorgesehenen Personenkreis.
Prüfe nach dem Test, ob der Einstieg und die Begrenzungen wirklich zum Anwendungsfall passen.

Gute Einsatzfälle¶

Typische sinnvolle Beispiele sind:

ein Service-Assistent im Kundenportal
ein interner Assistent für einen klar begrenzten Fachprozess
ein eingebetteter Assistent auf einer Projekt- oder Teamseite
ein temporärer Zugang für einen Workshop, Test oder Pilotbetrieb

Eigene Einstiegsseite (empfohlen)¶

Als Good Practice richtest du in deinem Portal oder auf deiner Website eine eigene Unterseite ein (z. B. /ai). Diese Seite wird serverseitig ausgeführt und ist der saubere Ort, an dem du den Übergang in den CLYE AI steuerst – nicht der direkte öffentliche Link mit festem Token.

Typischer Ablauf auf dieser Seite:

Anmeldung prüfen – z. B. anhand der Session-Cookies deines bestehenden Logins (oder deines SSO), ob der Nutzer überhaupt eingeloggt ist.
Berechtigung ableiten – aus deinen Rollen, Mandanten oder Produktregeln entscheidest du, ob und wie der Nutzer den Assistenten nutzen darf.
Parameter für den Link bauen – daraus werden die Felder für den Assistant Access Link zusammengesetzt (z. B. externe Nutzerkennung, Filter für sichtbare Inhalte, Feature-Flags wie Chat-Verlauf, Gültigkeitsdauer). Genau diese Struktur übergibst du im Body von POST /api/assistant-link.
API aufrufen – der Aufruf erfolgt vom Server (mit API-Schlüssel oder anderer serverseitiger Authentifizierung gegen den CLYE AI), nicht im Browser des Endnutzers.
Weiterleiten – die Antwort enthält unter anderem url; damit leitest du den Nutzer per HTTP-Umleitung (z. B. 302) in den CLYE AI.

So bleiben Geheimnisse und Berechtigungslogik bei dir; der Endnutzer sieht nur den kontrollierten Sprung in den Hub.

Rückkehr bei Ablauf oder erneuter Anmeldung: `loginUrl`¶

Über das optionale Feld loginUrl im Request an POST /api/assistant-link gibst du eine URL oder einen relativen Pfad an (z. B. deine Sign-in- oder Portal-Startseite). Der CLYE AI bzw. das Widget kann Nutzer dorthin zurückschicken, wenn der Zugang abgelaufen ist oder eine erneute Anmeldung nötig ist – statt sie ohne Orientierung im Widget zu lassen.

Was du vermeiden solltest¶

denselben Link dauerhaft breit weitergeben, obwohl er nur für einen kleinen Kreis gedacht ist
zu viele Funktionen freigeben, obwohl nur ein enger Anwendungsfall nötig ist
externe Nutzung ohne klare Ablaufzeit oder Verantwortlichkeit laufen lassen
einen Assistant Access Link als Ersatz für sauber geregelte Rollen und Freigaben im normalen Arbeitsbereich behandeln

Sicherheit im Alltag¶

Für Endnutzer ist vor allem diese Denkweise wichtig:

teile den Link nur so breit wie nötig
setze eine sinnvolle Ablaufzeit
gib nur die Funktionen frei, die wirklich gebraucht werden
teste den Link aus Sicht der Empfänger, bevor du ihn produktiv verteilst

Wenn sich Zweck oder Zielgruppe ändern, ist meist ein neuer Link besser als ein alter Link mit immer mehr Ausnahmen.

Wenn etwas nicht funktioniert¶

Prüfe zuerst diese naheliegenden Punkte:

Der Link ist möglicherweise abgelaufen.
Du bist im falschen Assistenten oder Bereich gelandet.
Bestimmte Funktionen wurden für diesen Link bewusst nicht freigegeben.
Der Link wurde für einen anderen Personenkreis oder Kontext erstellt.

Wenn der Einstieg grundsätzlich passt, aber wichtige Funktionen fehlen, ist meist nicht der Link kaputt, sondern die Freigabe zu eng gesetzt.

API¶

Die vollständige API Referenz findest du unter clye.ai/api.

POST /api/assistant-link

Assistent über die Chat-Route ansprechen (JavaScript)¶

Wenn du einen Assistant Access Link erzeugt hast, bekommst du im Response u. a. ein Feld token zurück.

Diesen token kannst du anschließend als assistantAccessToken im Body an POST /api/chat mitsenden, um den Assistenten programmgesteuert (z. B. aus deinem eigenen Frontend/Backend) anzusprechen.

Wichtig: Der Token ist ein Geheimnis. Er gehört in der Regel nicht dauerhaft in den Browser gespeichert und sollte immer serverseitig erzeugt werden.

Beispiel: Access Link serverseitig erzeugen und direkt chatten (Node.js)¶

Dieses Beispiel zeigt den typischen Flow:

POST /api/assistant-link (mit API-Key) → du bekommst token
POST /api/chat (mit assistantAccessToken) → du bekommst die Chat-Antwort

const baseUrl = process.env.CLYE_BASE_URL ?? "https://dein-hub.example";
const apiKey = process.env.CLYE_API_KEY; // API-Schlüssel (serverseitig!)
const botId = Number(process.env.CLYE_BOT_ID ?? 123);

async function createAssistantAccessToken() {
  const res = await fetch(`${baseUrl}/api/assistant-link`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      botId,
      ttlSeconds: 10 * 60,
      // optional (je nach Use-Case): loginUrl, permissionFilter, features, ...
    }),
  });

  if (!res.ok) throw new Error(`assistant-link fehlgeschlagen: HTTP ${res.status} ${await res.text()}`);
  const { token } = await res.json();
  return token;
}

async function chatOnce({ assistantAccessToken, text }) {
  const res = await fetch(`${baseUrl}/api/chat`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      botId,
      assistantAccessToken,
      messages: [{ role: "user", content: text }],
    }),
  });

  if (!res.ok) throw new Error(`chat fehlgeschlagen: HTTP ${res.status} ${await res.text()}`);

  // Hinweis: Je nach Client/Optionen kann die Route streamen (SSE).
  // Für einen ersten Test ist ein einfacher JSON-Read oft ausreichend.
  return await res.json();
}

const assistantAccessToken = await createAssistantAccessToken();
const result = await chatOnce({ assistantAccessToken, text: "Hallo! Was kannst du?" });
console.dir(result, { depth: null });

Wenn du ein eigenes Frontend mit dem AI SDK baust, findest du das passende Muster (inkl. assistantAccessToken im Request-Body) auch hier:

Chat einbetten und eigene Widgets

Typische Fallstricke¶

Token im Browser ausliefern : Ein API-Key gehört nie in den Browser. Erzeuge den Assistant Access Link serverseitig und gib maximal den kurzlebigen token an dein Frontend weiter.

Zu lange TTL / fehlender Ablauf : Setze eine sinnvolle ttlSeconds. Für Tests reichen oft 5–15 Minuten. Für produktive Flows ist „kürzer ist besser“.

Falsche Domain / Base-URL : Nutze als baseUrl immer deine Hub-/Whitelabel-Domain (nicht die Bot-Widget-Domain), damit /api/assistant-link und /api/chat erreichbar sind.

Streaming (SSE) statt JSON : POST /api/chat liefert aktuell immer Streaming (SSE). Ein einfaches await res.json() wird daher nicht funktionieren. Nutze einen SSE-Client (z. B. über EventSource-ähnliche Libraries, oder fetch + Stream-Parsing) oder verwende das AI SDK (empfohlen), das Streaming bereits korrekt verarbeitet.

CORS / Browser-Calls : In vielen Setups sind die CORS-Header so gesetzt, dass direkte Requests aus dem Frontend möglich sind. Falls es dennoch scheitert (z. B. wegen abweichender Origin, Proxy/CDN oder fehlender OPTIONS-Weiterleitung), ist der robuste Fallback: Browser → dein Backend → CLYE.

Chat-IDs und Fortsetzen : Wenn du Konversationen fortsetzen willst, verwende eine persistente id (Chat-ID) pro Session/Benutzer. Ohne id entsteht pro Request ggf. ein neuer Chat-Kontext.

Wenn du das Widget extern einbetten willst (iFrame) und verstehen möchtest, wann ein JWT-Widget reicht und wann du besser den Assistant Access Link nutzt, siehe:

Neuen Assistant Access Link erzeugen¶

Serverseitig (mit bestehender Anmeldung und Bot-Berechtigung) kannst du einen Link inklusive Token und Widget-URL anlegen.

Feld	Beschreibung
HTTP	`POST /api/assistant-link`
Kurz	Erzeugt `token`, `url` und das zugehörige `jwtPayload`.

Beispiel: Token per HTTP erstellen¶

Die Antwort von POST /api/assistant-link ist direkt ein JSON-Objekt mit token, url und jwtPayload (kein zusätzlicher result-Wrapper).

Authentifizierung für Skripte: Authorization: Bearer <API-Schlüssel> (wie in der API-Verwaltung erzeugt). Alternativ kannst du dieselbe Anfrage mit einer gültigen Browser-Session senden (Cookie Cookie: …), dann entfällt der Bearer-Header.

Ersetze Platzhalter (https://dein-hub.example, Bot-ID, Schlüssel) durch deine Werte.

JavaScript (z. B. Node.js 18+ mit fetch):

const baseUrl = process.env.CLYE_BASE_URL ?? "https://dein-hub.example";
const apiKey = process.env.CLYE_API_KEY; // API-Schlüssel aus den Einstellungen

const res = await fetch(`${baseUrl}/api/assistant-link`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${apiKey}`,
  },
  body: JSON.stringify({
    botId: 123, // numerische Bot-ID (Bearbeitungsrecht erforderlich)
    ttlSeconds: 3600, // optional; Standard ohne exp: 3600
  }),
});

if (!res.ok) {
  const err = await res.text();
  throw new Error(`HTTP ${res.status}: ${err}`);
}

const { token, url, jwtPayload } = await res.json();
console.log("token:", token);
console.log("widget url:", url);

Perl (Module HTTP::Tiny und JSON, z. B. aus CPAN):

use strict;
use warnings;
use HTTP::Tiny;
use JSON qw(encode_json decode_json);

my $base_url = $ENV{CLYE_BASE_URL} // 'https://dein-hub.example';
my $api_key  = $ENV{CLYE_API_KEY} or die "CLYE_API_KEY setzen\n";

my $http = HTTP::Tiny->new;
my $res = $http->post(
  "$base_url/api/assistant-link",
  {
    headers => {
      'Content-Type'  => 'application/json',
      'Authorization' => "Bearer $api_key",
    },
    content => encode_json({
      botId      => 123,
      ttlSeconds => 3600,
    }),
  },
);

die "HTTP $res->{status}: $res->{content}\n" unless $res->{success};

my $data = decode_json($res->{content});
print "token: $data->{token}\n";
print "url:   $data->{url}\n";

Kurz gesagt¶

Nutze einen Assistant Access Link, wenn du einen Assistenten gezielt, einfach und kontrolliert zugänglich machen willst. Gute Links sind klar begrenzt, leicht testbar und genau auf den vorgesehenen Anwendungsfall zugeschnitten.