Build Basics

Square API Access Tokens

Access token types Permalink Get a link to this section

Personal access tokens are used to get unlimited Square API access to resources in your own Square account.

OAuth access tokens are used to get authenticated and scoped Square API access to any Square account. Use them when your application accesses resources in other Square accounts on behalf of account owners. OAuth access tokens can also be used to access resources in your own Square account.

Note

OAuth access tokens for Connect v1 endpoints were scoped to a seller location. Square API endpoints require a seller-scoped OAuth token, which does not specify a location ID. In some cases, a Square API request body requires a location ID. In other cases, the location ID is optional. In either case, your application uses the Locations API to get a location ID when needed for a request.

To learn about migrating your v1 OAuth flow to the Square API OAuth flow, see Migrate to the Square API OAuth Flow.

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

If you need a token to access the resources in your own Square account for Sandbox testing or production, get it from the Developer Dashboard application that uses the token.

  1. Open the Developer Dashboard and select an application. The Credentials page for the selected application is shown.

  2. Set the dashboard mode to Production for a production access token or to Sandbox for a Sandbox access token (used in testing).

  3. Copy the Access Token in the Credentials section of the page.

    Important

    Store the copied personal access token in a secure location. Any developer can use that token in their own application to get full API access to your Square account.

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

Did you know?

For more secure access to your Square account, use an OAuth token. The OAuth flow enforces security in the following ways:

  • Challenges users to identify themselves as account owners before granting access to a Square account.

  • Limits the scope of access to a Square account and only after the authenticated user authorizes access.

  • Identifies the application being used to access a Square account.

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

In production, start the OAuth authentication flow by calling the OAuth API Authorize endpoint. On flow completion, an OAuth access token is returned to your application.

In testing, if you want to verify that your application can access a Square account with an OAuth token, but are not ready to add the OAuth flow, get an OAuth token in the Developer Dashboard on the OAuth page for your application. 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.

If you are ready to code and test an OAuth flow in your application, see OAuth API: Walkthrough to get started with the code.

Square API usage Permalink Get a link to this section

The following cURL example shows how an access token is provided in an Authorization header in a Payments API call to create a payment:

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
    "idempotency_key": "{{UNIQUE-KEY}}",
    "autocomplete": true,
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "source_id": "cnon:CBASEJIsHwzCJ7GvKt6EF1example"
    }
}' \
'https://connect.squareup.com/v2/payments'

Note

A personal access token also can be used in the previous cURL example.

Application credential types Permalink Get a link to this section

Applications registered with Square through the Developer Dashboard are assigned a set of credentials for accessing Square services. You need to use different credentials depending on how your application is used.

Note

An application credential is any piece of information that identifies, authenticates, or authorizes an application in some way. The most common form of credentials are access tokens (also called authorization tokens).

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. 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. Dashboard OAuth page
Personal access token Authorization Full-access (unscoped) access token. Grants full production access to the corresponding Square account. 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. 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. Dashboard Credentials page
Sandbox access token Authorization Full-access (unscoped) access token. Grants full access to the corresponding Square Sandbox account. 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. Dashboard OAuth page
Sandbox OAuth refresh token Authorization Special-purpose token. Used to obtain new access tokens when the current one expires. Dashboard OAuth page

More information Permalink Get a link to this section

If you are unfamiliar with authentication in a web application, read the following sections for an overview of basic authentication concepts.

What is an access token? Permalink Get a link to this section

Access token is the general term for an authorization credential. With Square APIs and SDKs, access tokens grant applications permission to access a specific Square account. Access tokens can be scoped or unscoped:

  • A scoped access token grants specific permissions that limit what the application can do with an account. For example, granting the application permission to read payment information but not granting it permission to process refunds for the account. OAuth tokens and mobile authorization tokens are examples of scoped access tokens.

  • An unscoped access token grants unlimited access to an account. Unscoped access means the application is impersonating the account owner and can do anything the account owner can do. A personal access token is an example of an unscoped access token.

Authentication versus authorization Permalink Get a link to this section

While authentication (sometimes abbreviated "authN") and authorization (sometimes abbreviated "authZ") are sometimes used interchangeably, the credentials serve very different purposes:

  • An authentication credential works with an identifier to prove that the credential holder (such as, a person or application) is who they claim to be. For example, when your bank prompts you for a username and then sends you a text with a numeric code, the numeric code is an authentication credential. It proves you really are the person associated with the username and password entered on the login page.

  • An authorization credential grants an authenticated credential holder permission to take a scoped set of actions required to do useful work, typically on behalf of a person or organization. For example, an application can be authorized for only-read access to payments data.