Access Tokens and Other Square Credentials

Link to section

Access token types

An access token allows access to resources (such as customers, orders, and payments) in a Square account. A valid access token is required when you use Square APIs to access resources in your own Square account or in other Square accounts.

Access tokens are sent as bearer tokens in the Authorization header of Square API requests, as shown in the following ListLocations request:

curl https://connect.squareup.com/v2/locations \ -H 'Square-Version: 2023-01-19' \ -H 'Authorization: Bearer {ACCESS_TOKEN}' \ -H 'Content-Type: application/json'

There are two types of access token:

  • Personal access token - Provides unrestricted Square API access to resources in a Square account. For example, you can use your own personal access token in Square API calls to perform any activity on any resource in your Square account.
  • OAuth access token - Provides authenticated and scoped Square API access to resources in a Square account. Applications use OAuth access tokens to access resources in other Square accounts on behalf of account owners. For example, Square sellers can sign up to use a third-party application that performs some activity on the resources in their account. In this case, the application makes Square API calls on behalf of a given Square seller.
Link to section

Get a personal access token

Each application you create in the Developer Dashboard provides a personal access token for production use and a separate Sandbox access token for testing in the Square Sandbox environment. These tokens grant full access to the resources in your own Square account.

To get a personal access token:

  1. Open the Developer Dashboard and choose an application.

    If needed, follow the steps in Get Started to create a Square account and an application. If you already have a Square account, you can create an application on the Applications page in the Developer Dashboard.

  2. In the left pane, choose Credentials.

  3. At the top of the page, choose Production mode to get your production access token or Sandbox mode to get your Sandbox access token.

  4. In the Production Access token or Sandbox Access token box, choose Show, and then copy your token.

The following animation shows how to copy your Sandbox access token from the Developer Dashboard in Sandbox mode.

An animation showing the process for getting the Sandbox access token from the Developer Dashboard.

Use the production access token for requests sent to the production environment at the connect.squareup.com domain.

curl https://connect.squareup.com/v2/locations \ -H 'Square-Version: 2023-09-25' \ -H 'Authorization: Bearer {PRODUCTION_ACCESS_TOKEN}' \ -H 'Content-Type: application/json'

Use the Sandbox access token for requests sent to the Sandbox environment at the connect.squareupsandbox.com domain.

curl https://connect.squareupsandbox.com/v2/locations \ -H 'Square-Version: 2023-09-25' \ -H 'Authorization: Bearer {SANDBOX_ACCESS_TOKEN}' \ -H 'Content-Type: application/json'

Using the wrong access token for the production or Sandbox environment results in an AUTHENTICATION_ERROR error with the UNAUTHORIZED error code.

When using a personal access token, the following guidelines apply:

  • It's strongly recommended that you don't hardcode your personal access token in your code. There are framework-specific considerations (for example, Ruby on Rail uses encrypted credentials) and platform-specific considerations (web and mobile applications) that apply for best practices for storing credentials securely. You should consult relevant documentation for specific environments. One option might be to leverage a secret management system such as Keywhiz.
  • Instead of using a personal access token to access resources in your account, you might use an OAuth access token, as described in the next section. You can then prevent accidentally sharing your personal access token with others.
  • Be careful when copy and pasting and when sharing cURL snippets. For example, during debugging you might copy and paste your example cURL code publicly on Stack Overflow or community forums. Make sure that these examples don't include your personal access token. Sharing a personal access token is similar to sharing an account password and could be used to impersonate the account owner. Redact any access tokens in the Authorization: Bearer header before sharing.
Link to section

Get an OAuth access token

The process of getting an access token depends on whether the token is used for an in-production application or for testing in the Square Sandbox during development:

  • Production - In-production applications can start the OAuth authentication flow by sending a user to the Square Authorize endpoint. On flow completion, an OAuth access token is returned to your application. If you're ready to code and test an OAuth flow in your application, see OAuth Walkthrough: Test Authorization with a Web Server. When your application is ready for production, see Move OAuth from the Sandbox to Production.

  • Sandbox - During development, before you're ready to add an OAuth flow, you can use Sandbox OAuth access tokens to test OAuth permissions. For example, you can generate an access token that grants specific permissions and then use it in your Sandbox API requests. This allows you to verify that your application can successfully access and manage resources in a Square account or gracefully handle authorization errors. To generate a Sandbox OAuth access token, you need to:

Link to section

Credential types

The following tables lists the access tokens and other credentials used for in Square development. Credential use is dependent on your development scenario.

CredentialTypeDescriptionUseObtained from
Application IDIdentificationRandom, unique ID assigned by SquareIdentifies your application in select Square API and SDK calls against the production environment. Also called a client ID.Developer Dashboard Credentials page
OAuth access tokenAuthorizationScoped access tokenGrants seller-scoped and limited access to a Square account by asking an authenticated user for explicit permissions.Programmatically using the OAuth API
OAuth refresh tokenAuthorizationSpecial-purpose tokenUsed to obtain new access tokens when the current one expires.Programmatically using the OAuth API
Application secretAuthenticationOAuth authentication credentialVerifies the identity of your application in OAuth API requests to get or refresh an OAuth access token. Also called a client secret.Developer Dashboard OAuth page
Personal access tokenAuthorizationFull-access (unscoped) access tokenGrants full production access to the corresponding Square account.Developer Dashboard Credentials page
Repository passwordAuthorizationRandom, unique ID assigned by SquareGrants your development environment access to the remote repositories that serve Reader SDK binariesDeveloper Dashboard Reader SDK page
Sandbox application IDIdentificationRandom, unique ID assigned by SquareIdentifies your application in select Square API and SDK calls against the Sandbox environment. Also called a Sandbox client ID.Developer Dashboard Credentials page
Sandbox access tokenAuthorizationFull-access (unscoped) access tokenGrants full access to the corresponding Square Sandbox account.Developer Dashboard Credentials page
Sandbox OAuth access tokenAuthorizationScoped access token for a Sandbox accountHas scoped resource permissions for a Sandbox application/account pair and used in OAuth requests.Developer Dashboard OAuth page
Sandbox OAuth refresh tokenAuthorizationSpecial-purpose tokenUsed to obtain new access tokens when the current one expires.Developer Dashboard OAuth page
Location IDN/ARandom, unique ID assigned by SquareNot a type of credential, but required for many Square API requests.Developer Dashboard Locations page or programmatically using the Locations API or Merchants API.
Link to section

See also