Build Basics

Access Tokens and Other Square Credentials

A credential is any piece of information that identifies, authenticates, or authorizes an application in some way. An access token is also a credential. This topic describes access tokens and other available credentials for Square.

Access token types Permalink Get a link to this section

A valid access token is required when you make a Square API call:

  • Access resources in your own Square account. A developer can make Square API calls to access resources in their own Square account.

  • Access resources in other Square seller accounts. A developer might create an application (referred to as a third-party application) that other Square sellers can sign up to use. In this case, the application makes Square API calls on behalf of the Square sellers.

Regardless, all these API requests must include a valid access token.

There are two types of access tokens:

  • 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 any Square account. Use OAuth access tokens when your application needs to access resources in other Square accounts on behalf of account owners.

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

An application you create in the Developer Dashboard (see Getting Started, Step 2: Create an application) provides a personal access token. You can use the token to access resources in your own Square account. Separate personal access tokens are generated for production use and testing in the Square Sandbox.

Assuming that you followed the Getting Started process to sign up for a Square account and created an application in the Developer Dashboard, you can find your personal access token by following these steps:

  1. Open the Developer Dashboard and choose an application.

  2. Choose the Credentials page.

  3. Set the Developer Dashboard mode to Production for a production access token or to Sandbox for a Sandbox access token.

The Sandbox or Production access token is your personal access token.

Developer Dashboard in Sandbox mode image-commerce plat-demo-credentials@2x (1)

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

  • It is strongly recommended that you do not hardcode your personal access token in your code. There are framework-specific (for example, Ruby on Rail uses encrypted credentials) and platform-specific (web and mobile applications) considerations that apply for best practices for storing credentials securely. You should consult relevant documentation for specific environments.

  • Instead of using a personal access token to access resources in your account, you might use an OAuth access token, as explained in the next section. You can then prevent accidentally sharing your personal access token with others.

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

Depending on whether you want an OAuth access token for use by an in-production application or for testing in the Square Sandbox, you have the following considerations:

  • In-production applications can start the OAuth authentication flow by calling the OAuth API Authorize endpoint. On flow completion, an OAuth access token is returned to your application. If you are ready to code and test an OAuth flow in your application, see OAuth API: Walkthrough to get started with the code.

  • 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 in 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 and Authorize a Sandbox Test Account.

Note

The Square Connect v1 API is an old API that is now deprecated. If you are migrating code to the latest Square API, note that OAuth access tokens for the deprecated Connect v1 endpoints were scoped to a seller location. Now the Square API endpoints require a seller-scoped OAuth token, which does not specify a location ID. If needed, you provide the location ID in the request body. To learn about migrating your v1 OAuth flow to the Square API OAuth flow, see Migrate to the Square API OAuth Flow.

Credential types Permalink Get a link to this section

As explained earlier, an access token is one of the credential types. The following table lists the available credentials you use depending on your scenario:

Credential Type Description Use Obtained from
Application ID Identification Random, unique ID assigned by Square Identifies your application in select Square API and SDK calls against the production environment. Also called a client ID. Developer Dashboard Credentials page
OAuth access token Authorization Scoped access token Grants seller-scoped and 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. Developer Dashboard OAuth page
Personal access token Authorization Full-access (unscoped) access token Grants full production access to the corresponding Square account. Developer 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. Developer Dashboard Reader SDK page
Sandbox application ID Identification Random, unique ID assigned by Square Identifies 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 token Authorization Full-access (unscoped) access token Grants full access to the corresponding Square Sandbox account. Developer 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. Developer Dashboard OAuth page
Sandbox OAuth refresh token Authorization Special-purpose token Used to obtain new access tokens when the current one expires. Developer Dashboard OAuth page