Entwickler
API-Dokumentation
Programmatischer Zugriff auf Toif-Lizenzen. Eigene Zugänge erstellst du selbst unter Einstellungen → API-Zugang.
Einführung
Alle Endpunkte folgen dem Muster /api/{version}/{modul}/{aktion}.
Aktuell verfügbare Versionen sind v1, v2 und v3 —
für eigene Integrationen empfehlen wir v2 oder v3.
Request- und Response-Body sind JSON.
Authentifizierung
Jeder Request benötigt ein API-Token im Authorization-Header:
Authorization: Bearer tfk_DEIN_TOKEN
Tokens erstellst du selbst unter Einstellungen → API-Zugang — sowohl als Kunde als auch als Reseller. Der Klartext-Token wird nur bei der Erstellung einmalig angezeigt; danach ist er nur noch als Hash gespeichert und kann nicht erneut abgerufen werden.
Antwortformat
Jede Antwort ist in dieselbe Hülle verpackt:
{
"metadata": { "project": "toifdash", "clientTransactionId": "...", "serverTransactionId": "..." },
"state": "success",
"message": "Action executed",
"data": { ... },
"timestamp": 1735900000,
"version_info": "..."
}
Bei Fehlern steht in state der Wert "error", message enthält die Fehlerbeschreibung, data ist leer.
Modul: license
Verwaltung von Toif-Lizenzen. Alle Aktionen werden per POST mit JSON-Body aufgerufen.
/api/v2/license/createLicense
Erstellt eine neue Toif-Lizenz.
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| user_id | string | ja | Kunden-ID, für die die Lizenz erstellt wird. |
| product_id | string | nein | Verknüpfte product-Zeile (Preis/Laufzeit). Ohne Angabe entsteht eine Lizenz ohne Abrechnungsbezug. |
curl
curl -X POST "https://www.toifdash.com/api/v2/license/createLicense" \
-H "Authorization: Bearer tfk_DEIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"user_id": "KUNDEN_ID"}'
Antwort (data)
{
"license_id": "...",
"key": "TOIF-XXXX-XXXX-XXXX-XXXX-CCCC",
"key_prefix": "TOIF-XXXX"
}
Der Klartext-Schlüssel wird nur in dieser einen Antwort zurückgegeben — anschließend ausschließlich als Hash gespeichert. Bei einem Reseller-Token wird die Lizenz automatisch dessen eigenem Konto zugeordnet (reseller_id kommt nie aus dem Payload).
/api/v2/license/listLicenses
Listet Lizenzen auf — reseller sehen nur eigene, admin/team optional gefiltert nach user_id.
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| user_id | string | nein | Nur für admin/team: Lizenzen eines bestimmten Kunden anzeigen. |
curl
curl -X POST "https://www.toifdash.com/api/v2/license/listLicenses" \
-H "Authorization: Bearer tfk_DEIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
Antwort (data)
{
"licenses": [
{ "id": "...", "key_prefix": "TOIF-XXXX", "status": "active", ... }
]
}
key_hash wird nie zurückgegeben.
/api/v2/license/getLicense
Liefert Details zu einer einzelnen Lizenz.
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| license_id | string | ja | ID der Lizenz. |
curl
curl -X POST "https://www.toifdash.com/api/v2/license/getLicense" \
-H "Authorization: Bearer tfk_DEIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"license_id": "LIZENZ_ID"}'
Antwort (data)
{
"license": { "id": "...", "key_prefix": "TOIF-XXXX", "status": "active", ... }
}
Nur erreichbar, wenn die Lizenz dem aufrufenden Kunden/Reseller gehört (oder admin/team).
/api/v2/license/revokeLicense
Widerruft eine Lizenz endgültig.
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| license_id | string | ja | ID der Lizenz. |
| reason | string | nein | Freitext-Begründung. |
curl
curl -X POST "https://www.toifdash.com/api/v2/license/revokeLicense" \
-H "Authorization: Bearer tfk_DEIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"license_id": "LIZENZ_ID"}'
Antwort (data)
{
"revoked": true
}
Nicht umkehrbar.
/api/v2/license/rotateLicenseKey
Stellt einen neuen Schlüssel für eine bestehende Lizenz aus, der alte wird sofort ungültig.
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| license_id | string | ja | ID der Lizenz. |
curl
curl -X POST "https://www.toifdash.com/api/v2/license/rotateLicenseKey" \
-H "Authorization: Bearer tfk_DEIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"license_id": "LIZENZ_ID"}'
Antwort (data)
{
"key": "TOIF-XXXX-XXXX-XXXX-XXXX-CCCC",
"key_prefix": "TOIF-XXXX"
}
Der neue Klartext-Schlüssel wird nur in dieser einen Antwort zurückgegeben.
Rechte & Sichtbarkeit
Die Berechtigung richtet sich nach der Rolle des Kontos, dem das Token gehört — nicht nach den beim Erstellen ausgewählten (rein informativen) Rechten:
- admin / team— uneingeschränkter Zugriff auf alle Lizenzen.
- reseller— nur Lizenzen, bei denen das eigene Konto als Reseller hinterlegt ist. Beim Erstellen wird das automatisch gesetzt, unabhängig davon, was im Payload steht.
- customer— nur die eigene(n) Lizenz(en).
Fehlercodes
| HTTP-Status | Bedeutung |
|---|---|
| 401 | Kein oder ungültiges/abgelaufenes/widerrufenes API-Token. |
| 400 | Fachlicher Fehler (z.B. "Keine Berechtigung", "Lizenz nicht gefunden", fehlender Pflichtparameter) — Details in message. |
| 404 | Modul oder Aktion existiert nicht. |