OAuth API

OAuth API: How it Works

A deeper look at the OAuth API

Applications that integrate with Square to take payments and manage inventory on behalf of a Square account must request permissions from the account holder to perform those actions. OAuth is the mechanism applications use to request permissions from account holders. For information about OAuth specification, see OAuth 2.0.

Process flow
Permalink Get a link to this section

The OAuth API includes 4 elements

  • Client — An application, not owned by Square using Square APIs or SDKs to integrate with Square services. Integrated clients are also sometimes called "3rd-party applications". 3rd-party applications can be single-user, custom solutions or official partner applications (like those listed in the Square App Marketplace).

  • Resource owner — The Square account holder that signup to use a 3rd-party application and grants the application permissions to access resources (such as catalog, customers, orders, and inventory) in their Square account.

  • Resource and Authorization servers — Square servers that issue OAuth access tokens and host resources in Square accounts. Neither developers nor Square account holders need to know the details.

Applications use the elements noted above in the following process to obtain permission from Square accounts and get OAuth tokens to perform tasks on their behalf.

  1. Applications configure and serve a link with the scope parameter set to the desired OAuth permissions. For example: https://connect.squareup.com/oauth2/authorize?client_id=exampleG9OlZgH7p4UszK_YIw-HeQ&scope=PAYMENTS_READ PAYMENTS_WRITE. Typically, applications serve OAuth links as part of the sign-up workflow.

  2. After the Square account holder clicks the authorization link, they are prompted with a permissions form hosted by Square.

  3. When the account holder clicks Allow on the permission form, Square sends an OAuth authorization code to the redirect URL configured for the application.

  4. The client application uses the (short-lived) OAuth authorization code to request an OAuth access token from the ObtainToken endpoint.

  5. The ObtainToken endpoint responds with an OAuth access token and a refresh token.

oauth-process-flow


Applications can use the OAuth access tokens to make subsequent calls with Square APIs and SDKs on behalf of the Square account holder and access resources in the associated Square account.

Important

OAuth access tokens do expire but the refresh tokens do not. An application can use the refresh token to obtain a new OAuth access token when the current OAuth access token expires. For more information, see OAuth access token management.

OAuth access token management
Permalink Get a link to this section

Square OAuth API supports multiple methods for acquiring an OAuth access token: exchange, refresh, and migration.

  • Exchange — the application received an authorization code and wants to exchange it for an OAuth access token.

  • Refresh — the application previously obtained an OAuth access token but the token has expired.

  • Migration — the application has an unrevoked, legacy OAuth access token that was obtained using Square-Version 2019-03-13 or earlier.

In the ObtainToken request applications specify the grant_type parameter to identify the method and provide relevant information in the request body.

Did you know?

Regardless of the method applications choose, the ObtainToken endpoint always returns two items in the response: an OAuth access token and a refresh token.