Überblick
Die Kurse der Zeitarbeit-Akademie laufen im Lernportal ONYX LMS. Firmenkunden mit Team-Zugang können dieses Portal über eine REST-API mit JSON ansprechen. Die API gehört zum Standardumfang eines Team-Zugangs.
Typische Aufgaben, die Ihr System damit selbst erledigt:
- Konten für neue Mitarbeitende anlegen oder Personen per E-Mail einladen
- Personen Gruppen zuordnen, etwa einer Niederlassung oder einem Team
- Kurse und Wissenspfade zuweisen, zum Beispiel Personaldisposition für neue Disponentinnen und Disponenten
- Fortschritt, Abschlüsse und Berichte abrufen
- Abschlüsse aus einem Vorsystem übernehmen
- Teilnahmebestätigungen als PDF abrufen
- per Webhook erfahren, wenn jemand einen Kurs abgeschlossen hat
Wer die API nutzen kann
Ein Team-Zugang hat im Lernportal einen eigenen Verwaltungsbereich. Dort legen Administratorinnen und Administratoren Ihrer Firma unter „API & Webhooks“ die Tokens an. Sie entscheiden dabei, welche Rechte ein Token bekommt und ob es eine Laufzeit von 1 bis 365 Tagen hat. Ohne Laufzeit gilt es, bis Sie es löschen.
Wer als Privatperson bucht, bekommt ein persönliches Lernkonto ohne Verwaltungsbereich. Ein solches Konto kann keine Tokens anlegen, die API steht deshalb nur Firmenkunden offen. Team-Zugänge planen Sie im Kurskonfigurator.
Token und Rechte
Jede Anfrage trägt das Token im Header:
Authorization: Bearer <TOKEN>
Das Lernportal zeigt das Token nur einmal, direkt nach dem Anlegen. Speichern Sie es sofort in Ihrem Passwortspeicher oder Ihrer Konfiguration. Geht es verloren, legen Sie ein neues an und löschen das alte im Verwaltungsbereich.
Geben Sie jedem Token nur die Rechte, die das anbindende System braucht. Fehlt ein Recht, antwortet die API mit 403.
| Recht | Erlaubt |
|---|---|
users.read | Konten und offene Einladungen lesen |
users.write | Konten anlegen und ändern, Personen einladen |
courses.read | Freigeschaltete Kurse und Einschreibungen lesen |
courses.write | In Kurse einschreiben, Abschlüsse übernehmen, Kurse einer Gruppe zuweisen |
learning_paths.read | Wissenspfade lesen |
learning_paths.write | Wissenspfade anlegen, ändern und Personen einschreiben |
groups.read | Gruppen und Mitglieder lesen |
groups.write | Gruppen anlegen, ändern und Mitglieder hinzufügen |
reports.read | Berichte zu Kursen, Lernenden und Aktivität lesen |
stats.read | Kennzahlen Ihres Zugangs lesen |
certificates.read | Teilnahmebestätigungen lesen und als PDF abrufen |
webhooks.read | Webhooks lesen |
webhooks.write | Webhooks anlegen |
Basis-URL und Version
Alle Pfade auf dieser Seite hängen Sie an diese Adresse an:
https://portal.onyx-lms.de/api/v1
Die Version steht im Pfad (/v1). Senden Sie bei jeder Anfrage Accept: application/json mit, bei Anfragen mit Inhalt zusätzlich Content-Type: application/json.
Die API kennt keine DELETE-Aufrufe. Konten, Gruppen und Webhooks entfernen Sie im Verwaltungsbereich.
Endpunkte
Die Tabelle nennt für jeden Aufruf das Recht, das das Token braucht. Die Kursliste zeigt nur die Kurse, die für Ihren Zugang freigeschaltet sind.
| Methode | Pfad | Zweck | Recht |
|---|---|---|---|
GET |
/users/users |
Konten auflisten (Filter role, search) oder einzeln abrufen | users.read |
POST |
/users |
Konto anlegen | users.write |
PATCH |
/users |
Lernendenkonto ändern, is_active: false deaktiviert es (Admin-Konten: 403) | users.write |
GET |
/invitations/invitations |
Offene Einladungen auflisten oder einzeln abrufen | users.read |
POST |
/invitations |
Person einladen | users.write |
GET |
/courses/courses |
Für Sie freigeschaltete Kurse | courses.read |
GET |
/courses |
Einschreibungen mit Status | courses.read |
POST |
/courses |
1 bis 100 Personen einschreiben | courses.write |
POST |
/courses |
Abschluss aus einem Vorsystem übernehmen | courses.write |
PUT |
/courses |
Kurs einer Gruppe zuweisen und alle Mitglieder einschreiben | courses.write |
GET |
/learning-paths/learning-paths/learning-paths |
Wissenspfade und ihre Kurse in Reihenfolge | learning_paths.read |
POST |
/learning-paths |
Wissenspfad anlegen | learning_paths.write |
PATCH |
/learning-paths |
Wissenspfad ändern | learning_paths.write |
POST |
/learning-paths |
1 bis 100 Personen einschreiben | learning_paths.write |
GET |
/groups/groups |
Gruppen auflisten oder einzeln abrufen | groups.read |
POST |
/groups |
Gruppe anlegen | groups.write |
PATCH |
/groups |
Gruppe ändern | groups.write |
GET |
/groups/users |
Mitglieder einer Gruppe, Gruppen einer Person | groups.read |
PUT |
/groups |
Mitglied hinzufügen | groups.write |
GET |
/reports/reports/reports/reports/reports |
Berichte zu Kursen, Lernenden und Aktivität | reports.read |
GET |
/stats |
Kennzahlen im Überblick | stats.read |
GET |
/certificates/certificates |
Teilnahmebestätigungen auflisten (Filter user_id, course_id, certificate_number, since) oder einzeln abrufen | certificates.read |
GET |
/certificates |
Teilnahmebestätigung als PDF | certificates.read |
GET |
/webhooks/webhooks |
Webhooks auflisten oder einzeln abrufen | webhooks.read |
POST |
/webhooks |
Webhook anlegen | webhooks.write |
Ein übernommener Abschluss schreibt die Person bei Bedarf zuerst in den Kurs ein und löst wie ein Abschluss im Lernportal den Webhook course.completed aus.
Das PDF einer Teilnahmebestätigung rufen Sie mit dem Recht certificates.read über GET /certificates/{id}/download ab. Es ist dasselbe Dokument, das Lernende im Lernbereich und die Administration im Verwaltungsbereich herunterladen. Die ID steht in der Liste /certificates, in der Antwort der Abschluss-Übernahme und im Webhook course.completed. Sie sehen nur Bestätigungen, die in Ihrem Zugang ausgestellt wurden. Bestätigungen deaktivierter Konten bleiben abrufbar. Die Antworten nennen IDs und keine Namen, und jeder PDF-Abruf wird protokolliert.
Beispiele
Die IDs sind Beispielwerte. Die echten Kurs-IDs Ihres Zugangs liefert GET /courses.
Drei Personen in den Kurs Personaldisposition einschreiben
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": []
}
}
enrolled_count zählt nur neue Einschreibungen. Wer schon eingeschrieben ist, bleibt unverändert. In rejected_user_ids stehen Personen, die das Lernportal nicht einschreiben konnte: einzelne, wenn für den Kurs keine Plätze mehr frei sind, oder der ganze Stapel, wenn der Kurs oder seine Freischaltung abgelaufen ist. Die Antwort hat trotzdem den Status 200.
Stand der Einschreibungen abrufen
curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
"https://portal.onyx-lms.de/api/v1/courses/12/enrollments"
{
"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"
}
]
}
status ist in_progress oder completed.
Webhook nach einem Kursabschluss
So kommt ein Abschluss bei Ihrem Webhook-Ziel an, hier für die Muster GmbH:
POST /lms-webhook HTTP/1.1
Host: hr.muster-gmbh.example
Content-Type: application/json
X-Webhook-Event: course.completed
X-Webhook-Timestamp: 2026-11-16T09:30:12.000000Z
X-Webhook-Signature: sha256=<hex>
{
"event": "course.completed",
"timestamp": "2026-11-16T09:30:12.000000Z",
"tenant_id": 42,
"data": {
"event_id": "6f1c2a9e-8d4b-4f0a-9b1e-2c3d4e5f6a7b",
"user_id": 1,
"course_id": 12,
"course_title": "Personaldisposition",
"completion_cycle": 1,
"certificate_number": "2026-42-0017",
"certificate_id": 87
}
}
certificate_number enthält die Nummer der Teilnahmebestätigung und certificate_id ihre ID für den PDF-Abruf über GET /certificates/{id}/download. Stellt der Kurs keine aus, sind beide null.
Webhooks
Mit Webhooks meldet das Lernportal Ereignisse an eine Adresse Ihres Systems, Sie müssen also nicht regelmäßig nachfragen. Webhooks legen Sie im Verwaltungsbereich oder per POST /webhooks an, mit Ziel-URL, den gewünschten Ereignissen und einer optionalen Beschreibung.
| Ereignis | Wird gesendet, wenn |
|---|---|
user.created | Ein Konto wurde einzeln angelegt: im Verwaltungsbereich, per POST /users oder per POST /invitations. Nicht bei CSV-Import, HRIS-Abgleich oder SSO-Anmeldung. |
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. Einschreibungen im Verwaltungsbereich lösen es nicht aus. |
course.completed | Eine Person hat einen Kurs abgeschlossen. |
course.restarted | Ein Kurs wurde für eine Person neu gestartet. |
learning_path.enrolled | Eine Person wurde über die API in einen Wissenspfad eingeschrieben. Einschreibungen im Verwaltungsbereich lösen es nicht aus. |
learning_path.completed | Eine Person hat alle Pflichtkurse eines Wissenspfads abgeschlossen. |
Signatur prüfen
Jeder Webhook hat ein Secret. Legen Sie den Webhook per POST /webhooks an, steht es einmalig in der Antwort. Im Verwaltungsbereich finden Sie es in der Bearbeitungsansicht des Webhooks. Jede Zustellung trägt den Header X-Webhook-Signature: sha256=<hex>, einen HMAC-SHA256 über den rohen Body mit diesem Secret. Rechnen Sie ihn über die empfangenen Bytes nach, nicht über neu kodiertes JSON, und vergleichen Sie zeitkonstant. Ein Beispiel in PHP:
$secret = getenv('LMS_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;
}
Dazu kommen die Header X-Webhook-Event mit dem Namen des Ereignisses und X-Webhook-Timestamp mit dem Sendezeitpunkt.
Zustellung und Wiederholungen
- Das Ziel muss öffentlich per HTTPS erreichbar sein. Weiterleitungen folgt das Lernportal nicht.
- Antworten Sie innerhalb von 10 Sekunden mit einem Status 2xx. Längere Verarbeitung erledigen Sie besser nach der Antwort.
- Schlägt eine Zustellung fehl, unternimmt das Lernportal insgesamt bis zu 5 Versuche, mit Abständen von 30 Sekunden, 2 Minuten, 5 Minuten und 15 Minuten.
- Nach 10 fehlgeschlagenen Versuchen in Folge schaltet das Lernportal den Webhook ab. Jeder erfolgreiche Versuch setzt den Zähler zurück.
- Ein Ereignis kann mehr als einmal ankommen.
course.completedundlearning_path.completedtragen deshalb eine festeevent_id, an der Sie doppelte Zustellungen erkennen.
Im Verwaltungsbereich sehen Sie jede Zustellung mit Statuscode und können einen Test-Aufruf an Ihr Ziel senden. Er kommt mit dem Ereignis test.ping an, rechnen Sie also auch mit diesem Namen.
Fehlercodes
Fehler kommen als JSON. Je nach Fall steht der Text im Feld error oder im Feld message. Werten Sie beide aus. error nutzen 401 und die fachlichen 403 und 422, zum Beispiel:
{ "error": "Insufficient permissions.", "required": "users.read" }
message kommt bei 404, 429 und einigen 403. Bei Eingabefehlern (422) nennt die Antwort außerdem unter errors die betroffenen Felder.
| Status | Bedeutung |
|---|---|
401 | Token fehlt, ist ungültig oder abgelaufen. |
403 | Dem Token fehlt das nötige Recht, der Zugang ist nicht aktiv, oder ein schreibender Aufruf kommt nach Vertragsende. |
404 | Die Ressource gibt es nicht oder sie gehört nicht zu Ihrem Zugang. |
422 | Die Eingabe ist ungültig oder verstößt gegen eine fachliche Regel. |
429 | Zu viele Anfragen. Warten Sie die Sekunden aus dem Header Retry-After ab. |
Endet Ihr Vertrag, bleibt die API eine Zeit lang lesbar. Lesende Aufrufe (GET) funktionieren weiter, schreibende beantwortet sie mit 403.
Anfragelimit und Seiten
Die API nimmt 600 Anfragen pro Minute je Client-IP an. Darüber hinaus antwortet sie mit 429. Der Header Retry-After sagt, nach wie vielen Sekunden Sie es wieder versuchen können.
Immer in Seiten liefern GET /users, /invitations, /reports/learners und /reports/activity. Die Listen /courses, /courses/{id}/enrollments, /learning-paths, /groups, /groups/{id}/users und /reports/courses liefern ohne Parameter alles auf einmal und blättern, sobald Sie page oder per_page mitschicken. Pro Seite kommen standardmäßig 25 Einträge, höchstens 100.
/reports/courses/{id}, /learning-paths/{id}/courses, /users/{id}/groups und /webhooks liefern immer die ganze Liste ohne meta.
GET https://portal.onyx-lms.de/api/v1/users?page=2&per_page=100
{
"data": [ … ],
"meta": { "current_page": 2, "last_page": 3, "per_page": 100, "total": 240 }
}
Datenschutz
Ein Token sieht nur die Daten Ihres eigenen Zugangs. Über die API löscht niemand Daten, dafür gibt es keinen Aufruf. Legen Sie Tokens mit möglichst wenigen Rechten an und löschen Sie Tokens, die Sie nicht mehr brauchen. Die Daten Ihrer Beschäftigten verarbeitet das Lernportal in Ihrem Auftrag. Welcher Vertrag zur Auftragsverarbeitung für Ihren Zugang gilt, sehen Firmen-Admins im Verwaltungsbereich unter „Verträge & Datenschutz“. Wie wir als Webseite personenbezogene Daten verarbeiten, steht in unserer Datenschutzerklärung.
Was die API nicht abdeckt
- Löschen: Konten, Gruppen und Webhooks entfernen Sie im Verwaltungsbereich.
- Lexikon und News der Akademie per API: auf Anfrage.
Pflichtunterweisungen und deren Nachweise gehören nicht zum Angebot der Zeitarbeit-Akademie. Sie laufen über ONYX LMS, das dafür eigene Funktionen in derselben API hat.
Fragen zur Anbindung
Sie wollen wissen, ob Ihr System passt, oder brauchen Lexikon und News per API? Schreiben Sie uns über die Kontaktseite.
