Authentifizierung und Ratenlimits
Authentifizierung
Jede Anfrage an /api/v1/* wird mit einem API-Schlüssel authentifiziert, übergeben als Bearer-Token im Authorization-Header:
Authorization: Bearer sy_...API-Schlüssel beginnen mit sy_ und werden nur einmal vollständig angezeigt — direkt bei der Erstellung. Danach sehen Sie nur noch die ersten und letzten vier Zeichen. Schlüssel laufen nach 30, 90 (Standard) oder 365 Tagen ab; ein abgelaufener Schlüssel liefert einen 401.
Erstellen Sie einen Schlüssel unter Einstellungen → Entwickler → API-Schlüssel. Jeder Schlüssel erhält eine Berechtigungsvorlage und eine Kundenzugriffs-Einstellung:
Nur Lesen — Lesezugriff auf jede Ressource — keine Schreibzugriffe, keine Veröffentlichung.
Vollzugriff — Lese- und Schreibzugriff überall, einschließlich Veröffentlichung und Teamverwaltung. Nur für Systeme, die Sie selbst vollständig kontrollieren.
Benutzerdefiniert — Wählen Sie Lesen, Lesen und Schreiben oder keinen Zugriff für jede Ressource. Die vollständige Liste sehen Sie bei der Erstellung des Schlüssels.
Alle Kunden — Der Schlüssel erreicht jeden Kunden Ihrer Agentur, auch später hinzugefügte.
Bestimmte Kunden — Der Schlüssel ist auf eine bei der Erstellung gewählte, feste Liste von Kunden beschränkt. Anfragen für andere Kunden erhalten einen 403.
Ratenlimits
Ratenlimits gelten pro Agentur, nicht pro Schlüssel, und richten sich nach Ihrem Plan. Wenden Sie sich an Ihr Account-Team, wenn Sie Ihr genaues Limit erfahren möchten.
Überschreiten Sie Ihr Limit, erhalten Sie eine 429-Antwort mit einem Retry-After-Header, der angibt, wie viele Sekunden Sie bis zum nächsten Versuch warten sollten.
Jede Fehlerantwort enthält ein Feld error, das beschreibt, was schiefgelaufen ist. Manche Fehlertypen enthalten zusätzliche Felder mit weiteren Details:
{
"error": "locationId is required"
}Statuscodes
200 | Die Anfrage war erfolgreich. |
201 | Eine Ressource wurde erstellt. |
400 | Der Anfrage fehlt ein erforderlicher Parameter, oder sie ist anderweitig fehlerhaft. |
401 | Der API-Schlüssel fehlt, ist ungültig, abgelaufen oder wurde widerrufen. |
403 | Dem Schlüssel fehlt die für diese Anfrage nötige Berechtigung, oder er ist für den betreffenden Kunden/Standort nicht autorisiert. |
404 | Die angeforderte Ressource existiert nicht oder gehört nicht zu Ihrer Agentur. |
409 | Die Anfrage widerspricht dem aktuellen Zustand der Ressource — etwa beim Versuch, bereits Archiviertes zu löschen. |
422 | Die Anfrage ist wohlgeformt, besteht aber die Validierung nicht — etwa bei einer ungültigen Kunden-ID. |
429 | Sie haben das Ratenlimit erreicht. Warten Sie die in Retry-After angegebene Anzahl Sekunden und versuchen Sie es dann erneut. |