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
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 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 Sandbox 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
Use the Sandbox access token for requests sent to the Sandbox environment at the
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: Bearerheader 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:
Production - 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.
Sandbox - During development, before you're ready to add an OAuth flow, you can use Sandbox OAuth access tokens to test OAuth permissions. For example, you can generate an access token that grants specific permissions and then use it in your Sandbox API requests. This allows you to verify that your application can successfully access and manage resources in a Square account or gracefully handle authorization errors. To generate a Sandbox OAuth access token, you need to:
The following tables lists the access tokens and other credentials used for in Square development. Credential use is dependent on your development scenario.