Authentifizierung
API-Schlüssel, Live- und Testschlüssel, Berechtigungen, Gültigkeit, Widerruf und die Übergabe des Schlüssels in einem Aufruf.
Die INTEGALL-API arbeitet ausschließlich mit API-Schlüsseln. Es gibt keine Benutzersitzungen und keine Cookies.
Einen Schlüssel erhalten#
Der Inhaber oder ein Administrator des Transportunternehmens erstellt einen Schlüssel im Unternehmensbereich unter EinstellungenIntegrationen › API und Webhooks. Zum Erstellen ist ein aktueller Code aus seiner Authenticator-App nötig. Siehe API-Schlüssel und Webhooks.
Der Schlüssel wird nur ein einziges Mal angezeigt. INTEGALL speichert danach nur einen Hash; niemand kann den Schlüssel später noch lesen.
Arten von Schlüsseln#
| Präfix | Art | Verhalten |
|---|---|---|
rr_live_ | Live | Liest und schreibt echte Daten. |
rr_test_ | Test | Liest Ihre echten Daten, aber ein Schreibaufruf wird nur geprüft und nicht gespeichert. Antworten enthalten "sandbox": true und den Header x-integall-sandbox: true. |
Ein Schlüssel hat die Form rr_live_xxxxxxxx_, gefolgt von 32 Zeichen. Die ersten 16 Zeichen (das Präfix) sehen Sie auch im Unternehmensbereich; daran erkennen Sie einen Schlüssel.
Berechtigungen (Scopes)#
| Berechtigung | Im Unternehmensbereich | Gibt Zugriff auf |
|---|---|---|
shipments:read | Sendungen lesen | GET /v1/shipments, GET /v1/shipments/{ref} |
shipments:write | Transporte anfragen | POST /v1/shipment-requests |
invoices:read | Rechnungen lesen | GET /v1/invoices |
webhooks:manage | Webhooks verwalten | kein Pfad in v1 |
Ein Aufruf ohne die passende Berechtigung erhält 403 mit dem Code E_SCOPE.
Den Schlüssel übergeben#
Verwenden Sie vorzugsweise den Header Authorization:
curl -H "Authorization: Bearer $INTEGALL_API_KEY" \
"https://api.integall.com/functions/v1/api-v1/v1/invoices"Der Header X-API-Key funktioniert ebenfalls:
curl -H "X-API-Key: $INTEGALL_API_KEY" \
"https://api.integall.com/functions/v1/api-v1/v1/invoices"Gültigkeit und Widerruf#
- Ein Schlüssel gilt bis zum Widerruf oder 30, 90 oder 365 Tage (Auswahl beim Erstellen).
- Ein Widerruf wirkt sofort, auch zwischen zwei Aufrufen: INTEGALL prüft den Schlüssel bei jedem Aufruf neu.
- Ein unbekannter, widerrufener oder abgelaufener Schlüssel erhält immer dieselbe Antwort:
401mitE_AUTH. INTEGALL nennt nie den Grund, warum ein Schlüssel ungültig ist. - Ein Unternehmen hat höchstens 20 aktive Schlüssel.
Einen Schlüssel ersetzen#
- Lassen Sie einen neuen Schlüssel erstellen.
- Hinterlegen Sie den neuen Schlüssel in Ihrem System.
- Lassen Sie den alten Schlüssel widerrufen.