API-Dokumentation
Überblick
Das Onyx LMS hat eine REST-API, die JSON sendet und empfängt. Sie gehört zum Standardumfang, Sie buchen sie nicht zusätzlich. Die Administration Ihres Unternehmens legt die Zugangs-Tokens selbst im Verwaltungsbereich unter „API & Webhooks“ an.
Typische Aufgaben, die Ihr Personal- oder HR-System über die API erledigt:
- Konten anlegen oder Personen einladen, Konten ändern und bei Austritt deaktivieren
- Personen Gruppen zuordnen, etwa einer Abteilung oder einem Standort
- Kurse und Lernpfade zuweisen
- Fortschritt, Abschlüsse und Berichte abrufen
- Abschlüsse aus einem Vorsystem mit dem ursprünglichen Datum übernehmen
- Teilnahmebestätigungen als PDF abrufen, etwa für die Personalakte
- Ereignisse wie neue Konten oder Abschlüsse per Webhook empfangen
Authentifizierung und Rechte
Jede Anfrage trägt das Token im Header:
Authorization: Bearer <TOKEN>
Das LMS zeigt ein neues Token genau einmal an, direkt nach dem Anlegen. Speichern Sie es sofort an einem sicheren Ort. Optional geben Sie eine Laufzeit von 1 bis 365 Tagen an, danach läuft das Token ab. Jedes Token gehört zu Ihrem Unternehmenskonto, und Sie können mehrere anlegen, zum Beispiel eines je angebundenem System.
Beim Anlegen wählen Sie die Rechte des Tokens. Geben Sie jeder Anbindung nur die Rechte, die sie braucht. Fehlt ein Recht, antwortet die API mit 403.
| Recht | Bedeutung |
|---|---|
users.read / users.write |
Konten und Einladungen lesen / Konten anlegen, ändern, einladen |
courses.read / courses.write |
Kurse und Einschreibungen lesen / einschreiben, Abschluss übernehmen, Kurs einer Gruppe zuweisen |
learning_paths.read / learning_paths.write |
Lernpfade lesen / anlegen, ändern, einschreiben |
groups.read / groups.write |
Gruppen und Mitglieder lesen / Gruppen anlegen, ändern, Mitglieder hinzufügen |
reports.read |
Berichte zu Kursen, Personen und Aktivität lesen |
stats.read |
Übersicht Ihres Unternehmenskontos lesen |
certificates.read |
Teilnahmebestätigungen lesen und als PDF abrufen |
signoffs.read / signoffs.write |
Unterweisungsnachweise lesen / gegenzeichnen |
webhooks.read / webhooks.write |
Webhooks lesen / anlegen |
Die Rechte für Unterweisungsnachweise bietet der Verwaltungsbereich an, wenn Ihr Unternehmen Kurse mit Unterweisungsnachweis nutzt.
Basis-URL und Version
Alle Pfade auf dieser Seite beginnen mit der Basis-URL:
https://portal.onyx-lms.de/api/v1
Die Version steht als Präfix im Pfad (/v1). Senden Sie bei jeder Anfrage den Header Accept: application/json, dann kommen auch Fehler als JSON zurück. Die Verbindung läuft immer verschlüsselt über HTTPS.
Die API löscht nichts: Es gibt keine DELETE-Endpunkte. Konten deaktivieren Sie per PATCH, Löschungen erledigt Ihre Administration im Verwaltungsbereich.
Endpunkte
Pfade relativ zur Basis-URL. Platzhalter in geschweiften Klammern sind die numerischen IDs aus den Antworten der API.
| Methode | Pfad | Zweck | Recht |
|---|---|---|---|
| GET | // |
Konten auflisten (Filter role, search) / ein Konto | users.read |
| POST | / |
Konto anlegen | users.write |
| PATCH | / |
Lernendenkonto ändern, mit is_active: false deaktivieren | users.write |
| GET | // |
Offene Einladungen / eine Einladung | users.read |
| POST | / |
Person einladen | users.write |
| GET | // |
Für Ihr Unternehmen freigeschaltete Kurse | courses.read |
| GET | / |
Einschreibungen mit Status | courses.read |
| POST | / |
1 bis 100 Personen einschreiben | courses.write |
| POST | / |
Abschluss aus einem Vorsystem übernehmen | courses.write |
| PUT | / |
Kurs einer Gruppe zuweisen, alle Mitglieder werden eingeschrieben | courses.write |
| GET | /// |
Lernpfade und ihre Kurse | learning_paths.read |
| POST | / |
Lernpfad anlegen | learning_paths.write |
| PATCH | / |
Lernpfad ändern | learning_paths.write |
| POST | / |
1 bis 100 Personen einschreiben | learning_paths.write |
| GET | // |
Gruppen / eine Gruppe | groups.read |
| POST | / |
Gruppe anlegen | groups.write |
| PATCH | / |
Gruppe ändern | groups.write |
| GET | // |
Mitglieder einer Gruppe / Gruppen einer Person | groups.read |
| PUT | / |
Person einer Gruppe hinzufügen | groups.write |
| GET | ///// |
Berichte je Kurs, je Person und jüngste Aktivität | reports.read |
| GET | / |
Übersicht: Konten, Kurse, Abschlüsse | stats.read |
| GET | // |
Teilnahmebestätigungen auflisten (Filter user_id, course_id, certificate_number, since) / eine Bestätigung | certificates.read |
| GET | / |
Teilnahmebestätigung als PDF | certificates.read |
| GET | // |
Unterweisungsnachweise | signoffs.read |
| POST | / |
Unterweisungsnachweis gegenzeichnen | signoffs.write |
| GET | // |
Webhooks / ein Webhook | webhooks.read |
| POST | / |
Webhook anlegen | webhooks.write |
Einen Abschluss übernimmt die API nur für Konten Ihres Unternehmens, die in Kurse eingeschrieben werden können. Liegt noch kein Abschluss vor, gilt das übergebene Datum, und das LMS stellt die Teilnahmebestätigung mit diesem Datum aus, sofern der Kurs eine vorsieht. Ein vorhandener Abschluss behält sein Datum. Für Kurse mit Unterweisungsnachweis geht das nicht, dort bestätigt die Person selbst im Kurs. Die API liefert Nummer und ID der Teilnahmebestätigung (certificate_number, certificate_id).
Das PDF einer Teilnahmebestätigung rufen Sie mit dem Recht certificates.read über GET /certificates/{id}/download ab. Es ist dasselbe Dokument, das die Lernenden im Lernbereich und Ihre Administration im Verwaltungsbereich herunterladen. Die ID steht in der Liste /certificates, in der Antwort der Abschluss-Übernahme und im Ereignis course.completed. Sie sehen nur Bestätigungen, die in Ihrem Unternehmen ausgestellt wurden. Bestätigungen deaktivierter Konten bleiben abrufbar. Wiederholt jemand einen Kurs, entsteht je Durchlauf eine eigene Bestätigung. Die Antworten nennen IDs und keine Namen, und jeder PDF-Abruf wird protokolliert.
Beim Gegenzeichnen nennen Sie die Person, die tatsächlich gegenzeichnet (countersigner_email, full_name). Sie braucht ein Konto in Ihrem Unternehmen und dieselbe Berechtigung wie im Portal. Die Unterweisung selbst bleibt beim Arbeitgeber (§ 12 ArbSchG); das LMS dokumentiert Bestätigung und Gegenzeichnung.
Beispiele
Drei Personen in Kurs 12 einschreiben
Anfrage
curl -s -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"user_ids":[1,2,3]}' \
"https://portal.onyx-lms.de/api/v1/courses/12/enroll"
Antwort
{
"data": {
"enrolled_count": 3,
"user_ids": [1, 2, 3],
"rejected_count": 0,
"rejected_user_ids": []
}
}
In rejected_user_ids stehen Personen, die das LMS nicht einschreiben konnte: weil keine Plätze mehr frei sind, oder alle, wenn der Kurs oder seine Freischaltung für Ihr Unternehmen abgelaufen ist. IDs, die zu keinem einschreibbaren Konto Ihres Unternehmens gehören, übergeht die API. Für jede neu eingeschriebene Person sendet das LMS das Ereignis course.enrolled.
Einschreibungen eines Kurses abrufen
Anfrage
curl -s \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
"https://portal.onyx-lms.de/api/v1/courses/12/enrollments?per_page=25"
Antwort
{
"data": [
{
"user_id": 1,
"email": "max.muster@example.com",
"name": "Max Muster",
"assigned_at": "2026-11-02 08:15:00",
"completed_at": null,
"current_section": 3,
"status": "in_progress"
}
],
"meta": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1 }
}
Webhook für einen Kursabschluss
So sieht eine Zustellung an Ihren Endpunkt aus (Signatur gekürzt):
POST /ihr/webhook-endpunkt
Content-Type: application/json
X-Webhook-Event: course.completed
X-Webhook-Timestamp: 2026-11-16T09:30:00.000000Z
X-Webhook-Signature: sha256=5d41402abc4b2a76b9719d911017c592...
{
"event": "course.completed",
"timestamp": "2026-11-16T09:30:00.000000Z",
"tenant_id": 7,
"data": {
"event_id": "9b2f6c1e-4a7d-4f0b-8e3a-2c5d7f9a1b4e",
"user_id": 1,
"course_id": 12,
"course_title": "Datenschutzunterweisung 2026",
"completion_cycle": 1,
"certificate_number": "2026-7-0123",
"certificate_id": 87
}
}
Webhooks
Mit Webhooks meldet das LMS Ereignisse an eine Adresse Ihres Systems, Sie müssen also nicht regelmäßig abfragen. Webhooks legen Sie im Verwaltungsbereich oder per POST /webhooks an, mit Ziel-URL, den gewünschten Ereignissen und optional einer Beschreibung. Die Ziel-URL muss öffentlich per HTTPS erreichbar sein.
| Ereignis | Wann es gesendet wird |
|---|---|
user.created | Ein Konto wurde über die API angelegt oder eingeladen oder einzeln im Verwaltungsbereich angelegt. |
user.updated | Ein Konto wurde geändert oder deaktiviert. |
user.deleted | Ein Konto wurde im Verwaltungsbereich gelöscht. |
course.enrolled | Eine Person wurde über die API in einen Kurs eingeschrieben, auch per Gruppenzuweisung über die API. |
course.completed | Eine Person hat einen Kurs abgeschlossen, auch bei übernommenem Abschluss. |
course.restarted | Ein Kurs wurde neu gestartet, etwa für die jährliche Wiederholung eines Pflichtkurses. |
learning_path.enrolled | Eine Person wurde über die API in einen Lernpfad eingeschrieben. |
learning_path.completed | Eine Person hat den letzten Pflichtkurs eines Lernpfads abgeschlossen. |
signoff.countersigned | Ein Unterweisungsnachweis wurde gegengezeichnet, im Portal oder per API. |
Jede Zustellung ist ein POST mit JSON. Der Body hat immer dieselbe Hülle: event, timestamp, tenant_id und data mit den Angaben zum Ereignis. Dazu kommen drei Header: X-Webhook-Event, X-Webhook-Timestamp und X-Webhook-Signature.
Signatur verifizieren
Jeder Webhook hat ein Secret. Legen Sie den Webhook per POST /webhooks an, steht es einmalig in der Antwort; im Verwaltungsbereich sehen Sie es in der Bearbeitungsansicht des Webhooks. Der Header X-Webhook-Signature hat die Form sha256=<hex>: ein HMAC-SHA256 über den rohen Request-Body, berechnet mit diesem Secret. Rechnen Sie den Wert über genau die empfangenen Bytes nach, nicht über neu kodiertes JSON, und vergleichen Sie zeitkonstant. In PHP sieht das so aus:
<?php
$secret = getenv('ONYX_WEBHOOK_SECRET');
$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = 'sha256='.hash_hmac('sha256', $rawBody, $secret);
if (! hash_equals($expected, $header)) {
http_response_code(401);
exit;
}
$event = json_decode($rawBody, true);
http_response_code(204);
Zustellung und Wiederholungen
Ihr Endpunkt sollte innerhalb von 10 Sekunden mit einem Status 2xx antworten. Weiterleitungen folgt das LMS nicht. Schlägt eine Zustellung fehl, versucht das LMS es erneut, insgesamt bis zu fünfmal: nach 30 Sekunden, nach 2, nach 5 und nach 15 Minuten. Jeder dieser Versuche zählt einzeln: Nach 10 fehlgeschlagenen Zustellversuchen in Folge deaktiviert das LMS den Webhook. Jede erfolgreiche Zustellung setzt diesen Zähler zurück.
Ein Ereignis kann deshalb mehr als einmal ankommen. course.completed und learning_path.completed tragen eine event_id, über die Sie doppelte Zustellungen erkennen. Im Verwaltungsbereich sehen Sie jede Zustellung mit Antwortcode und können einen Probeaufruf an Ihren Endpunkt schicken. Er sendet das Ereignis test.ping.
Fehlercodes
Fehler kommen als JSON. 401 sowie die fachlichen 403 und 422 nennen den Grund im Feld error, bei fehlenden Rechten auch das verlangte Recht:
{ "error": "Insufficient permissions.", "required": "users.read" }
404, 429 und einige 403 kommen im Standardformat mit dem Feld message. Bei Validierungsfehlern (422) enthält die Antwort message und je Feld eine Liste unter errors. Werten Sie deshalb beide Felder aus.
| Status | Bedeutung |
|---|---|
401 | Token fehlt, ist ungültig oder abgelaufen. |
403 | Dem Token fehlt das nötige Recht, das Unternehmenskonto ist nicht aktiv, oder die Aktion ist nicht erlaubt. |
404 | Die Ressource gibt es nicht oder sie gehört nicht zu Ihrem Unternehmenskonto. |
422 | Die Eingabe ist ungültig oder fachlich nicht möglich, zum Beispiel wenn keine Plätze mehr frei sind. |
429 | Das Anfragelimit ist überschritten. |
Ist Ihr Vertrag beendet und Ihr Unternehmenskonto nur noch lesbar, beantwortet die API ausschließlich lesende Anfragen (GET). Jeder Schreibversuch bekommt dann 403.
Anfragelimit und Seiten
Die API nimmt bis zu 600 Anfragen pro Minute je Client-IP an. Das Limit gilt für alle Endpunkte zusammen, unabhängig davon, welches Token die Anfragen sendet. Darüber antwortet sie mit 429. Warten Sie dann die Sekunden ab, die der Header Retry-After nennt.
Seitenweise Listen kommen als {"data": [...], "meta": {...}}. In meta stehen current_page, last_page, per_page und total. Mit page wählen Sie die Seite, mit per_page die Größe: 25 Einträge sind voreingestellt, höchstens 100 sind möglich.
Einige Listen liefern ohne diese Parameter alles auf einmal und dann ohne meta: /courses, /learning-paths, /groups, /groups/{id}/users, /courses/{id}/enrollments und /reports/courses. Sobald Sie page oder per_page mitsenden, kommen auch diese Listen seitenweise. Immer vollständig und ohne meta kommen /reports/courses/{id}, /learning-paths/{id}/courses, /users/{id}/groups und /webhooks.
Datenschutz
Jedes Token sieht und ändert nur die Daten Ihres Unternehmenskontos. Über die API löschen Sie keine Daten; ausgeschiedene Personen deaktivieren Sie, ihre Nachweise bleiben erhalten. Für die Verarbeitung personenbezogener Daten gilt die Vereinbarung zur Auftragsverarbeitung.
Zugang einrichten
Die Administration Ihres Unternehmens legt Tokens und Webhooks im Verwaltungsbereich unter „API & Webhooks“ an. Sie wählt dort die Rechte und auf Wunsch eine Laufzeit. Sie planen eine Anbindung und haben Fragen dazu? Schreiben Sie uns, wir besprechen sie gern mit Ihnen.