Skip to main content
Ogni richiesta all’API di Square Cloud porta con sé una chiave API. Crea le chiavi nelle impostazioni di sicurezza del tuo account: un account può averne fino a 10, ognuna con un nome, e il segreto di una nuova chiave viene mostrato una sola volta. Le chiavi create lì non scadono. Le chiavi che la CLI e l’estensione per VS Code ricevono quando le colleghi durano 90 giorni.

​
Invio della chiave

Invia la chiave nell’header Authorization. Il prefisso Bearer è facoltativo.
Conserva la chiave sul tuo server, in una variabile d’ambiente. Chiunque la possieda può agire sul tuo account entro i suoi scope. L’uso dell’API è soggetto ai Termini di Servizio e alla Politica di Uso Accettabile.
Preferisci un client tipizzato? Gli SDK di Square Cloud per JavaScript, Python e Go inviano la chiave per te e coprono ogni endpoint di questa reference.

​
Scope

Ogni chiave ha degli scope, che decidono cosa può fare. Una chiave con accesso completo copre tutti gli scope, inclusi quelli aggiunti in futuro. Una chiamata a un endpoint fuori dagli scope della chiave risponde 403 MISSING_SCOPE. Gli scope di una chiave esistente non si possono modificare: crea una nuova chiave con gli scope che ti servono. Anche la pagina di ogni endpoint indica il suo scope, subito sotto il campo Authorization.
Alcuni scope arrivano più lontano di quanto suggerisca il nome. files:write e apps:deploy eseguono codice a tua scelta nell’applicazione, snapshots:read scarica l’intera applicazione con le sue variabili d’ambiente, envs:read espone tutti i segreti dell’applicazione, databases:credentials fornisce la password del database, e l’accesso concesso con workspaces:manage continua a funzionare anche dopo la revoca della chiave. Dai a ogni integrazione solo gli scope di cui ha bisogno.

​
Limitare una chiave a risorse specifiche

Una chiave può anche essere limitata a un massimo di 30 applicazioni e database. Una chiamata su qualsiasi altra risorsa, o a un endpoint che riguarda l’intero account e non può essere ristretto a quelle risorse, risponde 403 RESOURCE_NOT_ALLOWED. Gli endpoint di elenco come Informazioni sull’account restituiscono solo le risorse coperte dalla chiave. Una chiave limitata non può avere gli scope blob:read o blob:write, perché i file salvati appartengono all’account e non a un’applicazione. Crea una chiave per le tue applicazioni e un’altra per Blob Storage.

​
Errori

Tutti gli altri codici sono in Errori.

​
Protezione dalle chiavi non valide

Per proteggere tutti gli account, l’API blocca temporaneamente un indirizzo IP che insiste con chiavi API che non appartengono a nessun account, rispondendo 429 RATE_LIMITED per un breve periodo. Le chiavi valide in uso normale non sono interessate. Se una richiesta riceve un 401, non ripeterla in loop: correggi o sostituisci la chiave.

​
Prossimi passi

La tua prima richiesta

URL base, una prima chiamata curl e il formato delle risposte.

Limiti e restrizioni

Budget di richieste per piano e regioni bloccate.