OAuth API

What It Does

Use OAuth to securely manage permissions and access to Square merchant accounts.

Backend
UI
OAuth API

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.

  • Testing support is not available in the current Square sandbox.

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 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.

Important

We recommend only using 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