Access Tokens and Other Square Credentials

Learn about the different types of access tokens and other credentials used to identify, authenticate, or authorize an application for Square development.

Access tokens are credentials that allow applications to securely interact with Square APIs. An access token authenticates your application and authorizes access to resources (such as customers, orders, and payments) in a Square account. Proper credential management and storage is critical for maintaining security.

You must provide a valid access token when using Square APIs to access resources in your own Square account or other Square accounts.

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 in Square API calls to access resources on behalf of account owners. For example, when Square sellers sign up to use an application, they grant the specific permissions (scopes) that the application needs to perform some activity on their account resources.

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

1. Sign in to the Developer Console and open an application. If needed, follow the steps in Get Started to create a Square account and an application.

2. In the left pane, choose Credentials.

3. Get your production or Sandbox access token:

   Production

   Sandbox

   1. At the top of the page, choose Production.
   2. In the Production Access token box, choose Show and copy your token.

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

The following guidelines apply to protecting personal access tokens:

• Don't hardcode access tokens in your code. Consult relevant documentation to find best practices for securely storing credentials, including framework-specific considerations (for example, encrypted credentials for Ruby on Rail) and platform-specific considerations (web or mobile applications). One option might be to use your cloud provider's secrets manager, such as AWS Secrets Manager, Google Cloud Secret Manager, or Azure Key Vault.

• Don't share access tokens. A personal access token can be used to impersonate the account owner and gain full access to account resources. For example, if you paste a cURL code snippet when debugging an issue with Square support or on community forums, make sure to redact the access token used in the Authorization header.

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

Access tokens are sent as bearer tokens in the Authorization header of Square API requests.

• Production requests use the https://connect.squareup.com/v2 base URL with an access token that's valid for the production environment, as shown in the following cURL request:

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

• Sandbox requests use the https://connect.squareupsandbox.com/v2 base URL with an access token that's valid for the Sandbox environment, as shown in the following cURL request:

  curl https://connect.squareupsandbox.com/v2/locations \
    -H 'Square-Version: 2024-07-17' \
    -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 backend Square SDK, the client is initialized with an access token and target environment, as shown in the following PHP SDK snippet:

$client = SquareClientBuilder::init()
  ->bearerAuthCredentials(
      BearerAuthCredentialsBuilder::init(
          $_ENV['SANDBOX_ACCESS_TOKEN']
      )
  )
  ->environment(Environment::SANDBOX)
  ->build();

For more information, see the following:

• Using the Square Java SDK
• Using the Square .NET SDK
• Using the Square Node.js SDK
• Using the Square PHP SDK
• Using the Square Python SDK
• Using the Square Ruby SDK

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

• Developer Console
• Square Sandbox
• OAuth API
• Move OAuth from the Sandbox to Production
• Refresh, Revoke, and Limit the Scope of OAuth Tokens