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.

You must protect access tokens and store them securely.

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 the application type (which determines whether you use the code flow or PKCE flow) and whether the token is used in production or for testing in the Square Sandbox during development.

Protect access tokens and store them securely - Store OAuth access tokens and refresh tokens in a secure storage solution. Don't expose them in client-side code or version control systems. You must refresh OAuth access tokens periodically before they expire. For more information, see OAuth API and OAuth Best Practices.

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. The following PHP SDK snippet initializes the client for the Sandbox:

$client = new SquareClient(
  token: $_ENV['SQUARE_ACCESS_TOKEN'],
  options: [
    'baseUrl' => Environments::Sandbox->value
  ]
);

For more information, see the quickstart guide:

• Go SDK
• Java SDK
• .NET SDK
• Node.js SDK
• PHP SDK
• Python SDK
• 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