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.
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.
Applications configure and serve a link with the
scopeparameter 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.
After the Square account holder clicks the authorization link, they are prompted with a permissions form hosted by Square.
When the account holder clicks Allow on the permission form, Square sends an OAuth authorization code to the redirect URL configured for the application.
The client application uses the (short-lived) OAuth authorization code to request an OAuth access token from the ObtainToken endpoint.
The ObtainToken endpoint responds with an OAuth access token and a refresh token.
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.
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.
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-Version2019-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.