API-Tokens anlegen

Mit einem API-Token greift eine Integration, zum Beispiel die Synchronisation mit einem Lernmanagementsystem, auf die Schnittstelle /api/v1 Ihres Workspaces zu. Ein Token handelt mit den Rechten der Person, der er gehört, und ist durch seine Bereiche weiter begrenzt.

Bevor Sie anfangen

• Sie haben im Hub die Aufgabe Workspace administrieren. Fracto Support sieht den Reiter API-Tokens nicht.
• Dem Token gehört später die Person, die ihn anlegt, also Sie. Er handelt mit Ihren aktuellen Rechten. Jede Anfrage prüft zusätzlich, ob Sie die Aktion noch ausführen dürfen. Legen Sie ihn deshalb nicht mit einem Konto an, das später seine Aufgaben verliert.
• Überlegen Sie, welche Bereiche die Integration braucht, und wählen Sie nur diese.

So legen Sie einen Token an

1. Öffnen Sie im Hub Organisation und den Reiter API-Tokens.

2. Klicken Sie auf Token erstellen.

3. Tragen Sie eine Bezeichnung ein, zum Beispiel „LMS-Synchronisation“ (bis 120 Zeichen).

4. Schalten Sie unter Bereiche ein, was der Token darf. Je Bereich gibt es einen Schalter mit dem Kurzcode darunter, zum Beispiel certificates:read. Es ist nichts vorgewählt, mindestens ein Bereich ist Pflicht. Die Liste hat 14 Bereiche, unter anderem Kurse lesen, Kursentwürfe bearbeiten, Lernende einschreiben, Zertifikate lesen, Personen lesen, Personen einladen und verwalten sowie Hersteller-Workspaces verwalten. Ein Schreib-Bereich schließt bei Personen, Organisationen, Hersteller-Workspaces und Einschreibungen den passenden Lese-Bereich ein. Wirksam ist am Ende nur, was Ihre Rechte erlauben.

   

5. Unter Ablaufdatum (optional) können Sie ein Datum wählen. Der Token gilt dann bis zum Ende dieses Tages in der Zeitzone Ihres Workspaces. Ohne Datum gilt er, bis er widerrufen wird.

6. Klicken Sie auf Token erstellen. Der Knopf ist erst aktiv, wenn Bezeichnung und mindestens ein Bereich da sind.

7. Im Fenster Token-Geheimnis kopieren klicken Sie neben dem Geheimnis auf Kopieren und speichern das Geheimnis sicher, zum Beispiel in der Verwaltung Ihrer Integration. Fracto zeigt es nicht noch einmal. Dann klicken Sie auf Fertig.

   

Die Integration sendet das Geheimnis als Bearer-Token im Kopf Authorization mit jeder Anfrage an /api/v1. In der Produktion beginnt es mit frt_live_.

Daran sehen Sie, dass es geklappt hat

Der Token steht in der Liste mit dem Status Aktiv und Ihnen als Eigentümer:in. In der Spalte Token stehen die Bezeichnung und darunter die ersten Zeichen des Geheimnisses (das Präfix). Bereiche zeigt die Bereiche als Kurzcode. Zuletzt verwendet zeigt „Nie“, bis die Integration ihn zum ersten Mal nutzt. Auch Anfragen, die wegen fehlender Rechte abgelehnt werden, zählen dort mit.

Erneuern, widerrufen, Verlauf

• Erneuern erscheint bei aktiven Tokens nur für die Eigentümerin oder den Eigentümer. Fracto widerruft den alten Token und legt einen neuen mit derselben Bezeichnung, denselben Bereichen und demselben Ablaufdatum an. Das neue Geheimnis zeigt es einmal, wie beim Anlegen. Tragen Sie es sofort in der Integration ein.
• Widerrufen kann jede Administration bei jedem aktiven Token. Fracto fragt nach: „Der Token funktioniert danach nicht mehr. Das lässt sich nicht rückgängig machen.“
• Verlauf zeigt, wer den Token erstellt, erneuert oder widerrufen hat, mit Zeitpunkt. Es erscheinen die letzten 100 Ereignisse.

Was danach passiert

• Ein Token handelt mit den Rechten, die seine Eigentümerin oder sein Eigentümer gerade hat. Fehlen sie, lehnt die Schnittstelle die Anfrage mit 403 ACCESS_DENIED ab. Fracto widerruft Tokens nicht, wenn jemand Aufgaben verliert oder der Arbeitszugang endet. Für Rechte, die die Person behält (zum Beispiel Ernennungen aus Channel oder Campus), wirkt der Token weiter, und nach dem Wiederaufnehmen oder einer neuen Einladung wirkt er wieder voll. Widerrufen Sie Tokens deshalb selbst, siehe Zugang entziehen oder pausieren.
• Nach dem Ablaufdatum nimmt Fracto den Token nicht mehr an. Die Liste zeigt ihn aber weiter als Aktiv, bis ihn jemand nach dem Ablauf verwendet. Erst dann steht dort Abgelaufen.
• Anlegen, Erneuern und Widerrufen stehen nur im Verlauf des Tokens, nicht im Aktivitätsprotokoll.

Wenn es nicht klappt

Meldung	Was sie bedeutet
Dafür fehlt dir die Berechtigung. Nur die Eigentümerin oder der Eigentümer kann einen Token erneuern.	Erscheint bei jeder Aktion, für die Ihnen das Recht fehlt, zum Beispiel weil Ihre Aufgaben sich inzwischen geändert haben. Der Text nennt immer das Erneuern. Erneuern sehen nur Eigentümerinnen und Eigentümer.
Die Aktion ist fehlgeschlagen. Bitte versuche es erneut.	Erneuern, Widerrufen oder der Verlauf hat nicht geklappt. Versuchen Sie es noch einmal, zum Beispiel wenn der Token inzwischen widerrufen wurde.
Die API-Tokens konnten nicht geladen werden.	Laden Sie die Seite neu.

Die Schnittstelle selbst antwortet mit diesen Fehlern: authentication_required (kein oder falsch geformter Bearer-Token), invalid_token (der Token ist ungültig, abgelaufen oder widerrufen), insufficient_scope (dem Token fehlt der nötige Bereich), ACCESS_DENIED mit Status 403 (der Eigentümerin oder dem Eigentümer fehlt das Recht für die Aktion, der häufigste Fall nach einem Entzug) und workspace_mismatch (bei Adressen mit Workspace: der Token gehört zu einem anderen Workspace).