Zum Inhalt

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

Der Link öffnet direkt den vorgesehenen Assistenten. Empfänger müssen nicht erst den ganzen AI HUB 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:

  1. Für wen ist der Link gedacht?
  2. Wie lange soll er gültig sein?
  3. Welche Funktionen sollen erlaubt sein?
  4. 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:

  1. Öffne die Einstellungen des passenden Assistenten oder Bereichs.
  2. Erzeuge dort einen Assistant Access Link.
  3. Lege Gültigkeit und erlaubte Funktionen fest.
  4. Teile den Link nur mit dem vorgesehenen Personenkreis.
  5. 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 AI HUB steuerst – nicht der direkte öffentliche Link mit festem Token.

Typischer Ablauf auf dieser Seite:

  1. Anmeldung prüfen – z. B. anhand der Session-Cookies deines bestehenden Logins (oder deines SSO), ob der Nutzer überhaupt eingeloggt ist.
  2. Berechtigung ableiten – aus deinen Rollen, Mandanten oder Produktregeln entscheidest du, ob und wie der Nutzer den Assistenten nutzen darf.
  3. 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.
  4. API aufrufen – der Aufruf erfolgt vom Server (mit API-Schlüssel oder anderer serverseitiger Authentifizierung gegen den AI HUB), nicht im Browser des Endnutzers.
  5. Weiterleiten – die Antwort enthält unter anderem url; damit leitest du den Nutzer per HTTP-Umleitung (z. B. 302) in den AI HUB.

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 AI HUB 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

/api#tag/assistant-link/POST/assistant-link

Widget & JWT (öffentlich)

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:

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.