Access Tokens and Other Square Credentials

A credential is any piece of information that identifies, authenticates, or authorizes an application in some way. This topic describes access tokens and other types of credentials used for Square development.

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 unlimited Square API access to resources in your own Square account.
• OAuth access token - Provides authenticated and scoped Square API access to resources in a Square account. OAuth access tokens allow applications 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.

Each application you create in the Developer Dashboard provides a personal access token for production use and a separate 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.

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-01-19' \
  -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-01-19' \
  -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.

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:

• 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.

• During development, you might not be ready to add an OAuth flow, but you might want to verify that your application can access a Square account with an OAuth token. You can use an OAuth access token for Square Sandbox testing. This requires you to create a Sandbox test account for your application in the Developer Dashboard. For more information about creating a token that limits application access to a scoped set of account resources, see Create a Sandbox test account and Authorize a Sandbox test account.

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

• Move OAuth from the Sandbox to Production
• Developer Dashboard
• OAuth API Overview
• Reader SDK Quickstart
• Square Sandbox