You can use Square APIs to manage resources on behalf of sellers. The OAuth API lets you request specific permissions from Square sellers to manage their resources and get OAuth tokens to call the Square APIs on their behalf. Using the access token and refresh token 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 onboarding a Square seller to your application. At a high level, the OAuth flow is as follows:
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. For more information, see Create the Redirect URL and Square Authorization Page URL.
The authorization page returns an authorization code.
Your application server uses that code, along with the client secret, to call the ObtainToken endpoint to get an access token and a refresh token. For more information, see Receive Seller Authorization and Manage Seller OAuth Tokens.
Use the access token to call the Square API when your application is performing 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.
The access token and refresh token are paired and the tokens define the same scope of permissions that a seller authorizes for your application. If the permission scope is changed, such as when your application requests additional permissions, your application must replace both tokens in secure application storage.
For a walkthrough that shows you how to set up a basic website that handles the Square OAuth flow, see OAuth API: Walkthrough.
The OAuth API requires HTTPS for the redirect URL for the authorization callback. For testing purposes using the Square Sandbox, you can use HTTP with localhost.
Authorization codes returned by the Square authorization page expire after 5 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 API Best Practices.
Refresh tokens do not expire. If you lose a refresh token, you must repeat the full OAuth authorization flow to obtain a new OAuth access token and refresh token. A refresh token only becomes invalid when the application's access has been completely revoked.
A refresh token can be used to get multiple active access tokens. You can call ObtainToken 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 resources to an application.
A webhook is a subscription that notifies you when a Square event occurs. For more information about using webhooks, see Webhooks Overview.
The OAuth API supports the following webhook event:
|oauth.authorization.revoked||Notifies an application whenever a seller revokes all access tokens and refresh tokens granted to the application.|
If you use the OAuth API to get authorization to manage a seller's resources, you should create a webhook that notifies you of the
oauth.authorization.revoked event. It indicates that a seller has removed your application's access to their resources. For a complete list of Square webhook events, see V2 Webhook Events Technical Reference.