Authentifizierung

Schulungstool nutzt API-Schlüssel, um den Zugriff auf die API zu ermöglichen; für delegierten Zugriff im Namen eines Administrators gibt es OAuth. Einen API-Schlüssel können Sie in Ihrem Administrationsbereich unter Einstellungen > Erweiterte Einstellungen > Entwickleroptionen generieren.

Schulungstool erwartet den API-Schlüssel in allen API-Anfragen im HTTP-Header:

Authorization: Token <API-Schlüssel>

Bearer <API-Schlüssel> wird ebenfalls akzeptiert.

Beispiel:

curl "https://api.schulungstool.de/v1/users/" \
  -H "Authorization: Token <API-Schlüssel>"

Ersetzen Sie <API-Schlüssel> durch Ihren API-Schlüssel.

Ohne gültigen Schlüssel antwortet die API mit Statuscode 401 und dem Fehlertyp AuthenticationFailed oder NotAuthenticated, siehe Fehler und Durchsatzbegrenzung.

Jeder API-Schlüssel trägt Zugriffsrechte (Scopes), die bestimmen, welche Endpunkte er aufrufen darf. Sie wählen sie je Ressource beim Generieren eines Schlüssels im Administrationsbereich unter Einstellungen > Erweiterte Einstellungen > Entwickleroptionen; ein Administrator kann sie dort jederzeit ändern, Änderungen gelten sofort. Schlüssel, die vor Einführung der Zugriffsrechte erstellt wurden, haben Vollzugriff.

write schließt read derselben Ressource immer ein. Login-Links melden den Aufrufer als den jeweiligen Benutzer an, deshalb sind sie bewusst ein separates Recht: users:write enthält sie nicht.

Der Scope folgt den Daten, die ein Endpunkt liefert, nicht seiner URL: So liefert GET /v1/groups/{id}/members/ Benutzer-Objekte und verlangt deshalb users:read. Sie müssen das nicht selbst herleiten; die API-Referenz nennt an jedem Endpunkt das benötigte Zugriffsrecht.

Fehlt einem Schlüssel das Zugriffsrecht, das ein Endpunkt verlangt, antwortet die API mit Statuscode 403 und dem Fehlertyp MissingScope. Die Antwort nennt den fehlenden Scope in error.required_scope und wiederholt ihn im Antwort-Header X-Required-Scope:

{
  "error": {
    "type": "MissingScope",
    "message": "This API key does not have the required access for this endpoint. Required scope: `courses:write` (Courses – Read and write). An administrator can grant it in the developer options of the admin area.",
    "required_scope": "courses:write",
    "doc_url": "https://docs.api.schulungstool.de/guides/authentication/#access-scopes",
    "request_id": "req_6b1c9d2e4f3a5078b6c4d2e0"
  }
}

GET /v1/me/ funktioniert mit jedem gültigen Schlüssel unabhängig von dessen Zugriffsrechten und liefert Name und Scopes des Schlüssels sowie das zugehörige Konto. Nutzen Sie den Endpunkt als Verbindungstest und um zu prüfen, welche Rechte ein Schlüssel trägt:

{
  "key": {
    "name": "Reporting (nur Lesen)",
    "uuid": "1e8f2d4c-9b7a-4f3e-8c21-5d6a7b8c9d0e",
    "scopes": ["course-ratings:read", "courses:read", "participations:read"]
  },
  "account": {
    "id": "7c1e4b2a-5d3f-4e8a-9b6c-1f2a3b4c5d6e",
    "name": "Demo GmbH",
    "domain": "demo.schulungstool.de"
  }
}

• Vergeben Sie jeder Integration nur die Zugriffsrechte, die sie wirklich braucht. Für Reporting- oder BI-Integrationen, die nur Daten abrufen, genügt ein Nur-Lese-Schlüssel; die Vorlage Alles auf Lesen im Administrationsbereich erstellt ihn mit einem Klick.
• Nutzen Sie je Integration einen eigenen Schlüssel – so können Sie eine Integration einschränken oder widerrufen, ohne die anderen zu berühren.
• Die Spalte Zuletzt verwendet im Administrationsbereich zeigt, wann ein Schlüssel zuletzt einen Request ausgeführt hat; seit Monaten unbenutzte Schlüssel sind Kandidaten für den Widerruf.
• Scheitern Requests mit 403, zeigt sie das API-Protokoll im Administrationsbereich (Einstellungen > Erweiterte Einstellungen > Entwickleroptionen > API-Protokoll) mit dem Fehlertyp MissingScope – ein Schlüssel mit fehlendem Zugriffsrecht fällt dort sofort auf.
• Um einen bestehenden Schlüssel mit Vollzugriff einzuschränken, gehen Sie von seiner tatsächlichen Nutzung aus: Filtern Sie das API-Protokoll auf den Schlüssel (Requests anzeigen im Menü des Schlüssels) und sehen Sie sich seine erfolgreichen Requests an. Die API-Referenz nennt in der ersten Zeile jeder Operation das benötigte Zugriffsrecht. Vergeben Sie über API-Schlüssel bearbeiten genau diese Zugriffsrechte und entziehen Sie die übrigen. Das API-Protokoll reicht 30 Tage zurück; seltener laufende Jobs tauchen dort nicht auf. Prüfen Sie diese im eigenen Code, oder achten Sie nach dem Einschränken auf MissingScope.

Neben API-Schlüsseln unterstützt die API OAuth 2.1 in zwei Formen:

• Delegierter Zugriff (Authorization Code mit PKCE): die richtige Wahl, wenn Administratoren eine App selbst mit ihrem Schulungstool-Konto verbinden, wie bei KI-Connectoren. Bei der Freigabe wählen sie die Zugriffsrechte der Verbindung.
• Konto-Zugriff für Serveranwendungen (Client Credentials): Ein Administrator richtet die App einmal für das Konto ein; danach holt sie sich Tokens selbst, ohne dass sich jemand anmeldet.

• Flow: Authorization Code mit PKCE (S256). Der Authorization-Server ist https://auth.schulungstool.de; die API nennt ihn unter https://api.schulungstool.de/.well-known/oauth-protected-resource (RFC 9728), und jede 401-Antwort verweist im WWW-Authenticate-Header dorthin. Standard-OAuth-Clients finden so alles selbst. Fordern Sie die API als Audience des Tokens mit dem resource-Parameter https://api.schulungstool.de an (RFC 8707).
• Freigabe: Ein Administrator des Kontos gibt jede Verbindung frei und wählt die gewährten Zugriffsrechte einzeln aus. Login-Links sind nie vorausgewählt; der Administrator muss sie bewusst ankreuzen.
• Tokens: Access-Tokens (schulungstool_oat_…) sind 1 Stunde gültig und werden wie API-Schlüssel im Header Authorization: Bearer gesendet; Refresh-Tokens sind 30 Tage gültig und rotieren bei jeder Erneuerung. Ein abgelaufenes Access-Token antwortet mit 401 und dem Fehlertyp TokenExpired: Erneuern Sie es mit dem Refresh-Token. Ein Token behält die Zugriffsrechte, mit denen es ausgestellt wurde; beim Erneuern darf scope sie einschränken, aber nie erweitern. GET /v1/me/ zeigt die Zugriffsrechte des Tokens.
• Trennen: Administratoren können jede Verbindung jederzeit im Administrationsbereich unter Einstellungen > Erweiterte Einstellungen > Entwickleroptionen trennen. Eine Verbindung endet auch, wenn der Administrator, der sie freigegeben hat, deaktiviert oder gelöscht wird oder die Administrator-Rolle verliert.

Eine eigene App registrieren Sie im Administrationsbereich unter Einstellungen > Erweiterte Einstellungen > Entwickleroptionen > Eigene OAuth-Apps mit ihren Redirect-URIs und dem App-Typ:

• Serveranwendung: bekommt Client-ID und Client-Secret (wird einmalig angezeigt). Am Token-Endpunkt authentifiziert sie sich per HTTP Basic oder mit client_id und client_secret im Request-Body.
• Desktop-, Mobil- oder Browser-App: bekommt nur eine Client-ID und nutzt PKCE.

KI-Clients wie Claude oder ChatGPT registrieren sich selbst per Dynamic Client Registration; wie Sie sie verbinden, zeigt der MCP-Guide.

Eine Serveranwendung lässt sich für das ganze Schulungstool-Konto einrichten: Der Zugriff gehört dem Konto, nicht einer Person, und bleibt bestehen, wenn der einrichtende Administrator das Unternehmen verlässt. Wählen Sie im Administrationsbereich an Ihrer App Für dieses Konto einrichten und legen Sie die Zugriffsrechte fest; der Dialog zeigt eine fertige Token-Anfrage. Die App holt sich Tokens dann per Client-Credentials-Flow:

curl "https://auth.schulungstool.de/token" \
  -u "<Client-ID>:<Client-Secret>" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=users:read participations:read"

scope ist optional und darf die bei der Einrichtung gewählten Zugriffsrechte nur einschränken; ohne scope trägt das Token alle. Diese Tokens sind 1 Stunde gültig und haben kein Refresh-Token: Holen Sie nach Ablauf ein neues. Konto-Zugriff anpassen ändert die Zugriffsrechte, Trennen unter Verbundene Apps beendet den Zugriff sofort.

Verifizierte Partner-Apps können dieselbe Einrichtung anderen Konten anbieten: Sie starten den Authorization-Flow mit access_mode=account und nennen das Konto am Token-Endpunkt über den Body-Parameter account, die ID des Kontos, wie sie GET /v1/me/ in account.id liefert (nach der Installation speichern; Adressen können sich ändern, die ID nicht). Für die Verifizierung Ihrer App sprechen Sie uns an.

Für Server-zu-Server-Integrationen des eigenen Kontos bleiben API-Schlüssel eine gleichwertige Alternative.

In der API-Referenz können Sie jede Anfrage über Test Request direkt aus dem Browser senden. Hinterlegen Sie dazu Ihren API-Schlüssel im Feld Auth: Er bleibt ausschließlich in Ihrem Browserfenster, wird nicht gespeichert und ist nach dem Neuladen der Seite wieder weg. Beachten Sie: Die Anfragen gehen an die produktive API, schreibende Aufrufe (etwa POST oder DELETE) verändern also echte Daten.