Skip to main content
Chaque requête vers l’API Square Cloud transporte une clé API. Créez vos clés dans les paramètres de sécurité de votre compte : un compte peut en détenir jusqu’à 10, chacune avec un nom, et le secret d’une nouvelle clé ne s’affiche qu’une seule fois. Les clés que vous y créez n’expirent pas. Les clés que reçoivent la CLI et l’extension VS Code lorsque vous les connectez sont valables 90 jours.

​
Envoyer la clé

Envoyez la clé dans l’en-tête Authorization. Le préfixe Bearer est facultatif.
Conservez la clé sur votre serveur, dans une variable d’environnement. Toute personne qui la détient peut agir sur votre compte dans la limite de ses scopes. L’utilisation de l’API est soumise aux Conditions d’utilisation et à la Politique d’utilisation acceptable.
Vous préférez un client typé ? Les SDK Square Cloud pour JavaScript, Python et Go envoient la clé pour vous et couvrent chaque endpoint de cette référence.

​
Scopes

Chaque clé porte des scopes, qui déterminent ce qu’elle peut faire. Une clé à accès complet couvre tous les scopes, y compris ceux ajoutés plus tard. Un appel à un endpoint hors des scopes de la clé répond 403 MISSING_SCOPE. Les scopes d’une clé existante ne sont pas modifiables : créez une nouvelle clé avec les scopes dont vous avez besoin. Chaque page d’endpoint indique aussi son scope, juste sous le champ Authorization.
Certains scopes vont plus loin que leur nom ne le laisse penser. files:write et apps:deploy exécutent du code de votre choix dans l’application, snapshots:read télécharge toute l’application avec ses variables d’environnement, envs:read expose chaque secret de l’application, databases:credentials donne le mot de passe de la base de données, et l’accès accordé avec workspaces:manage continue de fonctionner après la révocation de la clé. Ne donnez à chaque intégration que les scopes dont elle a besoin.

​
Restreindre une clé à des ressources

Une clé peut aussi être limitée à 30 applications et bases de données au maximum. Un appel concernant toute autre ressource, ou visant un endpoint à l’échelle du compte qui ne peut pas être restreint à ces ressources, répond 403 RESOURCE_NOT_ALLOWED. Les endpoints de liste comme Informations sur le compte ne renvoient que les ressources couvertes par la clé. Une clé restreinte ne peut pas porter les scopes blob:read ou blob:write, car les fichiers stockés appartiennent au compte et non à une application. Créez une clé pour vos applications et une autre pour Blob Storage.

​
Erreurs

Tous les autres codes figurent dans Erreurs.

​
Protection contre les clés invalides

Pour protéger tous les comptes, l’API bloque temporairement une adresse IP qui insiste avec des clés API n’appartenant à aucun compte, et répond 429 RATE_LIMITED pendant une courte période. Les clés valides utilisées normalement ne sont pas concernées. Si une requête reçoit un 401, ne la relancez pas en boucle : corrigez ou remplacez la clé.

​
Étapes suivantes

Votre première requête

URL de base, un premier appel curl et le format de réponse.

Limites et restrictions

Budgets de requêtes par plan et régions bloquées.