What It Does


Requirements and limitations
Permalink Get a link to this section

  • The OAuth API requires HTTPS.

  • Square OAuth access tokens expire after 30 days with a grace period of 15 days. After expiration, applications must generate a new OAuth access token using the refresh token received when the authorization was first granted.

  • Refresh tokens do not expire. However, if you lose a refresh token, you must repeat the full OAuth flow to obtain a new OAuth access token and a refresh token.

OAuth components
Permalink Get a link to this section

At a high level, the OAuth 2.0 protocol is a series of credential exchanges between:

  • A user account

  • An application frontend (e.g., website or mobile app)

  • An application backend

  • An OAuth HTTPS endpoint

These exchanges happen when a user clicks a link or button to grant access to their account. At the end of the exchange, the application receives an OAuth access token that can be used to make API calls on behalf of the user.

Unlike a password or unscoped access token, which lets applications impersonate the account owner, OAuth access tokens are scoped to specific permissions that limit the behavior of the application. Scoped access tokens provides number of security advantages:

  • Applications do not request or store user credentials for the targeted account.

  • Users do not need to sign in to their account every time they use the application.

  • Users can grant access for specific resources instead of allowing access to their entire account. For example, merchants may grant access to only their items library without exposing their transaction history.

  • Users can revoke access for a potentially insecure application without affecting other applications or having to reset their password.

The Square OAuth API lets applications request and obtain permission from a Square production account or Sandbox v2 testing account to make API calls on behalf of that account. Applications can request individual permissions so that users do not need to grant full access to their Square accounts.

Use the Square API Explorer (beta) to see the Obtain Token endpoint at work and discover more capabilities of the OAuth API.


We recommend only using sandbox personal access tokens for development and testing. If a production application using a personal access token is compromised the attacker will have complete access to the associated account.

Get started

Use the build guide to integrate with the OAuth API