Build Basics

Square API Access Tokens

Get Connect API access tokens for your app.

Access token types
Permalink Get a link to this section

Personal access tokens are used to get unlimited Connect API access to resources in your own Square account.

OAuth access tokens are used to get authenticated and scoped Connect API access to any Square account. Use them when your app accesses resources in other Square accounts on behalf of account owners. OAuth access tokens can also be used to access resources in your own Square account.

Get a personal access token
Permalink Get a link to this section

If you need a token to access the resources in your own Square account for sandbox testing or production, get it from the Developer Dashboard app that will use the token.

  1. Open the Developer Dashboard and select an application. The Credentials page for the selected app is shown.

  2. Set the dashboard mode to Production Settings for a production access token or Sandbox Settings for a sandbox access token (used in testing).

  3. Copy the Access Token in the Credentials section of the page.

Important

Store the copied personal access token in a secure location. Any developer can use that token in their own app to get full API access to your Square account.


Developer Dashboard in Sandbox Settings mode image-test sandbox-01@2x

Did you know?

For more secure access to your Square account, use an OAuth token. The OAuth flow enforces security in the following ways:

  • Challenges a user to identify themselves as account owners before granting access to a Square account.

  • Limits the scope of access to a Square account and only after the authenticated user authorizes access.

  • Identifies the app being used to access a Square account.

Get an OAuth access token
Permalink Get a link to this section

In production, start the OAuth authentication flow by calling the OAuth API Authorize endpoint. On flow completion, an OAuth access token is returned to your app.

In testing, if you want to verify your app can access a Square account with an OAuth token but aren't ready to add the OAuth flow, get an OAuth token in the Developer Portal on the OAuth page for your app . See Create and Authorize a Sandbox Account for more information about creating a token that limits app access to a scoped set of account resources.

If you are ready to code and test an OAuth flow in your app, read about building with OAuth to get started with the code.

Connect API usage
Permalink Get a link to this section

The following cURL example shows how an access token is provided in an Authorization header in a Payments API call to create a payment:

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
    "idempotency_key": "{{UNIQUE-KEY}}",
    "autocomplete": true,
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "source_id": "cnon:CBASEJIsHwzCJ7GvKt6EF1example"
    }
}' \
'https://connect.squareup.com/v2/payments'

Note: A personal access token also can be used in the previous cURL example.

Application credential types
Permalink Get a link to this section

Applications registered with Square through the Developer Dashboard are assigned a set of credentials for accessing Square services. You will need to use different credentials depending on how your application will be used.

Note

An application credential is any piece of information that identifies, authenticates, or authorizes an application in some way. The most common form of credentials are access tokens (also called authorization tokens).

Credential Type Description Use Obtained from
Application ID Identification Random, unique ID assigned by Square. Identifies your application in select Connect API and Square SDK calls against the production environment. Also called a client ID. Dashboard Credentials page
OAuth access token Authorization Scoped access token. Grants limited access to a Square account by asking an authenticated user for explicit permissions. Programmatically using the OAuth API.
OAuth refresh token Authorization Special-purpose token. Used to obtain new access tokens when the current one expires. Programmatically using the OAuth API.
Application Secret Authentication OAuth authentication credential. Verifies the identity of your application in OAuth API requests to get or refresh an OAuth access token. Dashboard OAuth page
Personal access token Authorization Full-access (unscoped) access token. Grants full production access to the corresponding Square account. Dashboard Credentials page
Repository password Authorization Random, unique ID assigned by Square. Grants your development environment access to the remote repositories that serve Reader SDK binaries. Dashboard
Reader SDK page
Sandbox Application ID Identification Random, unique ID assigned by Square. Identifies your application in select Connect API and Square SDK calls against the sandbox environment. Also called a sandbox client ID. Dashboard Credentials page
Sandbox access token Authorization Full-access (unscoped) access token. Grants full access to the corresponding sandbox Square account. Dashboard Credentials page
Sandbox OAuth access token Authorization Scoped access token for a sandbox account Has scoped resource permissions for a sandbox application/account pair and used in OAuth requests. Dashboard OAuth page
Sandbox OAuth refresh token Authorization Special-purpose token. Used to obtain new access tokens when the current one expires Dashboard OAuth page

More information
Permalink Get a link to this section

If you are unfamiliar with authentication in a web app, read the following sections for an overview of basic authentication concepts.

What is an access token?
Permalink Get a link to this section

Access token is the general term for an authorization credential. With Square APIs and SDKs, access tokens grant applications permission to access a specific Square account. Access tokens can be scoped or unscoped.

A scoped access token grants specific permissions that limit what the application can do with an account. For example, granting the application permission to read payment information but not granting it permission to process refunds for the account. OAuth tokens and mobile authorization tokens are examples of scoped access tokens.

An unscoped access token grants unlimited access to an account. Unscoped access means the application is impersonating the account owner and can do anything the account owner can do. A personal access token is an example of an unscoped access token. !!!

Authentication versus authorization
Permalink Get a link to this section

While authentication (sometimes abbreviated "authN") and authorization (sometimes abbreviated "authZ") are sometimes used interchangeably, the credentials serve very different purposes.

An authentication credential works with an identifier to prove that the credential holder (e.g., a person or application) is who they claim to be. For example, when your bank prompts for a username and then sends you a text with a numeric code, the numeric code is an authentication credential. It proves you really are the person associated with the username and password entered on the login page.

An authorization credential grants an authenticated credential holder permission to take a scoped set of actions required to do useful work, typically on behalf of a person or organization. For example, an app can be authorized for only read access to payments data.