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.
Access Tokens and Other Square Credentials
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:
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.
In the left pane, choose Credentials.
At the top of the page, choose Production mode to get your production access token or Sandbox mode to get your Sandbox access token.
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.
Note
The Square Connect V1 API is deprecated. If you're migrating code to the latest Square API, note that OAuth access tokens for the deprecated Connect V1 endpoints were scoped to a seller location. In contrast, OAuth access tokens for Square API endpoints are scoped to a seller. To specify a location when calling a Square API endpoint, provide the location ID in the request. 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. Also called a client secret. | 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 |
Location ID | N/A | Random, unique ID assigned by Square | Not a type of credential, but required for many Square API requests. | Developer Dashboard Locations page or programmatically using the Locations API or Merchants API. |
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.