Skip to main content
Jede Anfrage an die Square Cloud API trägt einen API-Schlüssel. Schlüssel erstellst du in deinen Sicherheitseinstellungen des Kontos: Ein Konto hat bis zu 10 davon, jeder mit einem Namen, und das Geheimnis eines neuen Schlüssels wird nur einmal angezeigt. Dort erstellte Schlüssel laufen nicht ab. Die Schlüssel, die die CLI und die VS-Code-Erweiterung beim Verbinden erhalten, gelten 90 Tage.

​
Den Schlüssel senden

Sende den Schlüssel im Header Authorization. Das Präfix Bearer ist optional.
Bewahre den Schlüssel auf deinem Server in einer Umgebungsvariable auf. Wer ihn hat, kann im Rahmen seiner Scopes in deinem Konto handeln. Die Nutzung der API unterliegt den Nutzungsbedingungen und der Richtlinie zur akzeptablen Nutzung.
Lieber ein typisierter Client? Die Square Cloud SDKs für JavaScript, Python und Go senden den Schlüssel für dich und kapseln jeden Endpoint dieser Referenz.

​
Scopes

Jeder Schlüssel hat Scopes, die festlegen, was er darf. Ein Schlüssel mit Vollzugriff deckt jeden Scope ab, auch später hinzugekommene. Ein Aufruf eines Endpoints außerhalb der Scopes des Schlüssels antwortet mit 403 MISSING_SCOPE. Die Scopes eines bestehenden Schlüssels lassen sich nicht bearbeiten: Erstelle einen neuen Schlüssel mit den Scopes, die du brauchst. Jede Endpoint-Seite nennt ihren Scope ebenfalls, direkt unter dem Feld Authorization.
Manche Scopes reichen weiter, als ihr Name vermuten lässt. files:write und apps:deploy führen beliebigen Code in der Anwendung aus, snapshots:read lädt die ganze Anwendung samt Umgebungsvariablen herunter, envs:read legt jedes Geheimnis der Anwendung offen, databases:credentials liefert das Datenbankpasswort, und mit workspaces:manage gewährter Zugriff funktioniert auch nach dem Widerruf des Schlüssels weiter. Gib jeder Integration nur die Scopes, die sie braucht.

​
Einen Schlüssel auf Ressourcen beschränken

Ein Schlüssel lässt sich außerdem auf bis zu 30 Anwendungen und Datenbanken beschränken. Ein Aufruf zu einer anderen Ressource oder an einen kontoweiten Endpoint, der sich nicht auf diese Ressourcen eingrenzen lässt, antwortet mit 403 RESOURCE_NOT_ALLOWED. Auflistende Endpoints wie Kontoinformationen liefern nur die Ressourcen, die der Schlüssel abdeckt. Ein beschränkter Schlüssel kann die Scopes blob:read und blob:write nicht tragen, weil gespeicherte Dateien zum Konto gehören und nicht zu einer Anwendung. Erstelle einen Schlüssel für deine Anwendungen und einen weiteren für Blob Storage.

​
Fehler

Alle anderen Codes stehen unter Fehler.

​
Schutz vor ungültigen Schlüsseln

Zum Schutz aller Konten sperrt die API vorübergehend eine IP-Adresse, die hartnäckig API-Schlüssel sendet, die zu keinem Konto gehören, und antwortet für kurze Zeit mit 429 RATE_LIMITED. Gültige Schlüssel im normalen Einsatz sind nicht betroffen. Bekommt eine Anfrage ein 401, wiederhole sie nicht in einer Schleife: Korrigiere oder ersetze den Schlüssel.

​
Nächste Schritte

Deine erste Anfrage

Basis-URL, ein erster curl-Aufruf und das Antwortformat.

Limits und Einschränkungen

Anfragebudgets pro Plan und gesperrte Regionen.