OAuth API

OAuth Overview

As a developer, you can use Square APIs to manage resources on behalf of a seller. The OAuth API enables you to request specific permissions from Square sellers to manage their resources and get access tokens to call the Square APIs on their behalf. Using the access tokens you receive using OAuth, you can build applications that integrate with Square.

The Square OAuth API uses the OAuth 2 protocol to get permission from the owner of the seller account to manage specific types of resources in that account.

Usually, you make OAuth part of your setup process when you onboard a Square seller to your application. At a high level, the OAuth flow is as follows:

  1. Your application requests authorization from the owner of the seller account by sending the owner to the Square authorization page to grant access to your application.

  2. The authorization page returns an authorization code.

  3. Your application server uses that code, along with the client secret, to call the Obtain Token endpoint to get an access token and a refresh token.

You use the access token to call the Square API when your application is doing work on behalf of the seller's account. The access token has a limited lifetime. Your application uses the refresh token to get a new access token periodically so that it maintains access. Store both the access token and refresh token securely.

Requirements and limitations
Permalink Get a link to this section

  • The OAuth API requires HTTPS for the redirect URL for the authorization callback. For testing purposes, you can use HTTP with localhost.

  • Authorization codes returned by the Square authorization page expire after five minutes. An authorization code can only be used once.

  • Square OAuth access tokens expire after 30 days. To maintain access, you must generate a new OAuth access token using the refresh token received with the original authorization. For more information about managing OAuth access tokens and refresh tokens, see OAuth Production Best Practices.

  • Refresh tokens do not expire. If you lose a refresh token, you must repeat the full OAuth flow to obtain a new OAuth access token and a refresh token. A refresh token only becomes invalid when the application's access has been completely revoked. For more information, see Revoking Access.

  • A refresh token can be used to get multiple active access tokens. You can call Obtain Token multiple times with a refresh token. Each access token expires 30 days after it is obtained and each can be individually revoked. Developers sometimes choose to have multiple access tokens for a seller when the seller has a multi-store eCommerce site and wants a separate access token for each store.

  • OAuth 2.0 is not the same as Single Sign-On (SSO) or authentication in general. OAuth is an authorization protocol. OAuth can be used to build an authentication system; however, that is not the purpose of the Square OAuth API. Its purpose is to enable sellers to grant permissions to their account's resources to an application.