Grundlagen
Authentifizierung und API-Schlüssel
API-Schlüssel sind Ihrem Konto, einer Umgebung und festgelegten Berechtigungen zugeordnet.
Bearer-Authentifizierung
Erstellen und widerrufen Sie API-Schlüssel in der geschützten Schlüsselverwaltung Ihres Dashboards. Übertragen Sie den Schlüssel anschließend im HTTP-Header Authorization. Schlüssel in Query-Parametern, JSON-Bodies oder URLs werden nicht unterstützt.
Der Live-Zugriff muss für Ihr Unternehmen separat und manuell durch Digital-Zulassen freigegeben werden. Eine Dashboard-Freigabe genügt dafür nicht. Ohne Live-Freigabe sind die Erstellung und Verwendung von Live-Schlüsseln gesperrt; die API antwortet mit HTTP 403 und live_access_not_approved. Testschlüssel können Sie unabhängig davon verwenden.
Authorization: Bearer dz_test_••••••••••••••••••••Das Präfix zeigt die Umgebung
Auch das unternehmensweite Minutenbudget wird getrennt nach Test- und Produktivumgebung geführt. Testverkehr verbraucht damit nicht das Unternehmensbudget der Produktivumgebung und umgekehrt.
| Präfix | Umgebung | Zulässige Nutzung |
|---|---|---|
dz_test_… | Test | Halter, Checks, Reservierungen, Anträge und Bestellungen ohne externe Übergabe testen. |
dz_live_… | Produktiv | Echte Ressourcen Ihres Kontos verarbeiten. |
Berechtigungen nach Aufgabe
Weisen Sie jedem Schlüssel nur die benötigten Scopes zu. Bei fehlendem Scope antwortet die API mit HTTP 403 und insufficient_scope.
| Scope | Erlaubte öffentliche Operationen |
|---|---|
applications:write | Produktive und Testanträge anlegen sowie Testereignisse auslösen. |
applications:read | Anträge auflisten oder einzeln einschließlich Status und Ergebnisse lesen sowie Gebühren auflisten. |
documents:read | Antragsdokumente und Gebührenbescheide abrufen. |
holders:read | Halter und Halterverifizierungen lesen. |
holders:write | Halter anlegen und aktualisieren. |
holders:verify | Prüfversuche starten und Halternachweise übertragen. |
license_plates:read | Zulassungsstellen, bestehende Verfügbarkeitschecks und Reservierungen lesen. |
license_plates:write | Kennzeichenchecks und produktive oder simulierte Reservierungsaufträge anlegen. |
orders:read | Antragsgebundene Zusatzleistungsbestellungen und Versandstatus lesen. |
orders:write | Angeforderte Bestellnachweise, insbesondere für Feinstaubplaketten, übertragen. |
signature_profiles:read | Signaturprofile auflisten und abrufen. |
signature_profiles:write | Signaturprofile anlegen, aktualisieren und Logos hochladen. |
Schlüsselverwaltung
- Speichern Sie Schlüssel ausschließlich serverseitig in einem Secret Store oder einer geschützten Umgebungsvariable.
- Übertragen Sie Schlüssel nur über HTTPS und niemals aus öffentlich ausgeliefertem Browser-JavaScript.
- Geben Sie jedem Schlüssel einen eindeutigen, beschreibenden Namen und nur die benötigten Rechte.
- Rotieren Sie Schlüssel regelmäßig und sofort bei Verdacht auf Offenlegung.
- Protokollieren Sie höchstens das Schlüsselpräfix oder die im Dashboard sichtbare Schlüssel-ID.
Rotation ohne Unterbrechung
- 01
Neuen Schlüssel erstellen
Legen Sie einen zweiten Schlüssel mit denselben minimalen Rechten an.
- 02
Integration umstellen
Verteilen Sie den neuen Wert und prüfen Sie einen authentifizierten Leseaufruf.
- 03
Alten Schlüssel widerrufen
Entziehen Sie den bisherigen Schlüssel erst nach dem erfolgreichen Wechsel.