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.
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 for 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.
An application you create in the Developer Dashboard (see Get Started, Step 1: Create an account and 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 Get 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:
Open the Developer Dashboard and choose an application.
In the left pane, choose Credentials.
At the top of the page, choose Production mode for a production access token or Sandbox mode for a Sandbox access token.
The Sandbox or production access token is your personal access token.
Developer Dashboard in Sandbox mode
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 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 explained 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 buildwithsquare.slack. Make sure that these examples do not include your personal access token. Sharing a personal access token is similar to sharing your account password. Redact any access tokens in the
Authorization: Bearerheader before sharing.
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 sending a user to the Square 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 Walkthrough: Authorization Using a Test Account.
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.
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.
The following tables lists the access tokens and other credentials used for in Square development. Credential use is dependent on your development 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 |
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.