Skip to main content
Every request to the Square Cloud API carries an API key. Create keys in your account security settings: an account holds up to 10 of them, each with a name, and the secret of a new key is shown only once. Keys you create there don’t expire. The keys the CLI and the VS Code extension receive when you connect them last 90 days.

​
Sending the key

Send the key in the Authorization header. The Bearer prefix is optional.
Keep the key on your server, in an environment variable. Anyone who has it can act on your account within its scopes. The use of the API is subject to the Terms of Service and the Acceptable Use Policy.
Prefer a typed client? The Square Cloud SDKs for JavaScript, Python and Go send the key for you and wrap every endpoint of this reference.

​
Scopes

Each key carries scopes, which decide what it can do. A key with full access covers every scope, including the ones added later. A call to an endpoint outside the key’s scopes answers 403 MISSING_SCOPE. Scopes can’t be edited on an existing key: create a new key with the scopes you need. Each endpoint page also names its scope, right below the Authorization field.
Some scopes reach further than their name suggests. files:write and apps:deploy run code of your choice in the application, snapshots:read downloads the whole application with its environment variables, envs:read exposes every secret of the application, databases:credentials gives the database password, and access granted with workspaces:manage keeps working after the key is revoked. Give each integration only the scopes it needs.

​
Restricting a key to resources

A key can also be limited to up to 30 applications and databases. A call about any other resource, or to an account-wide endpoint that can’t be narrowed to those resources, answers 403 RESOURCE_NOT_ALLOWED. Listing endpoints such as Account Information return only the resources the key covers. A restricted key can’t carry the blob:read or blob:write scopes, because stored files belong to the account and not to an application. Create one key for your applications and another one for Blob Storage.

​
Errors

Every other code is in Errors.

​
Protection against invalid keys

To protect every account, the API temporarily blocks an IP address that insists on API keys that don’t belong to any account, answering 429 RATE_LIMITED for a short period. Valid keys in normal use are not affected. If a request gets a 401, don’t retry it in a loop: fix or replace the key.

​
Next steps

Your first request

Base URL, a first curl call and the response format.

Limits and restrictions

Request budgets per plan and blocked regions.