OAuth API Overview

The OAuth API lets you connect your application to a seller's account using OAuth.

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. This is the process where client applications obtain an authorization code that is then redeemed to get an access token and refresh token. These tokens allow you to manage resources for a seller and are used when calling the Square APIs. The OAuth API lets you request specific permissions from Square sellers to manage their resources and get access tokens to call the Square APIs on their behalf. Usually, you make OAuth part of your setup process when onboarding a Square seller to your application.

Square offers two types of OAuth: a code flow and a PKCE (Proof Key for Code Exchange) flow:

  • The code flow is an OAuth flow that requires a confidential client to pass in the client_id and client_secret values when redeeming an authorization code from Square. Passing these types of sensitive data requires you to use a confidential client.

  • The PKCE flow is an OAuth flow for public clients that removes the need to pass the client_secret and replaces it with a code_verifier. The code_verifier is a unique string that the client application creates for every authorization request. The PKCE flow must be used by any client that cannot safely store secrets in the application, such as mobile applications, single-page applications, and native desktop applications.

Important

A confidential client is one where the application runs on a server and the seller interacts with the application by using a browser or an API. A public client, on the other hand, is a mobile or desktop application where the seller has the actual application on their device. Public clients shouldn't store secrets because the secret is stored inside the application and a debugger or disassembler can be used to find the secret.

The OAuth API uses the following OAuth terms when using the code flow or PKCE flow:

  • Authorization code - A code that is returned when calling the Authorize endpoint. This code is used to redeem an access token and a refresh token.
  • Access token - A token that grants access to a client's resources and has some privileges attached to it. Access tokens expire after a certain amount of time.
  • Refresh token - A token that is used to generate more access tokens. If you use the code flow, refresh tokens are valid until their access is revoked. If you use the PKCE flow, refresh tokens are single-use tokens and expire after 90 days.

Square doesn't support OpenID or other single sign-on (SSO) protocols on top of the OAuth implementation.

Link to section

Code flow

The OAuth code flow is designed for confidential client applications that run on a server and can store client information securely. The code flow uses the following OAuth terms:

  • client_id - The ID that is associated with an application using the OAuth process. This is a public variable and is called the Application ID in the Developer Dashboard on the OAuth page.
  • client_secret - The secret that is associated with an application. It is used to redeem refresh tokens and should never be shared by a public client. Leaking this information is equivalent to leaking a password. This variable is called the Application secret in the Developer Dashboard on the OAuth page.

The code flow process is as follows:

  1. Your client application creates an authorization URL that you provide to the seller who approves the permissions you requested. The authorization URL contacts the Authorize endpoint.
  2. The Authorize endpoint returns an authorization code.
  3. The client calls the ObtainToken endpoint and provides the client ID, client secret, and the authorization code.
  4. The ObtainToken endpoint returns an access token and a refresh token.

A graphic showing the process flow for the OAuth code flow.

Link to section

PKCE flow

The OAuth PKCE flow is designed for public clients that shouldn't store secret information in their application. The PKCE process removes the need to pass the client_secret and doesn't require a secure backend server. The PKCE flow adds two new terms:

  • code_verifier - A unique random string generated by the client.
  • code_challenge - A Base64-URL-encoded string of the SHA256 hash of the code verifier.

The PKCE flow process is as follows:

  1. The client application creates an authorization URL that is the authorization request. The client application creates the code_verifier and uses the Base64-URL-encoding of its SHA256 hash to create theĀ code_challenge. The authorization request calls the Authorize endpoint and includes the code_challenge. You provide this URL to the seller who approves the permissions you request.
  2. The Authorize endpoint returns an authorization code. The server retains the code_challenge.
  3. The client calls the ObtainToken endpoint and provides the client ID, code_verifier, and authorization code. The server verifies that the code_verifier is the same value as the value that was encrypted to create the code_challenge.
  4. The ObtainToken endpoint returns an access token and a single-use refresh token that expires in 90 days.

A graphic showing the process flow for the OAuth PKCE flow.

Link to section

Determine which OAuth flow applies to your application

If your application has a confidential client, one that is able to securely authenticate with an authorization server and is able to store the client_secret securely, you should use the OAuth code flow for your application. Using the OAuth code flow lets you receive multiple-use refresh tokens that don't expire.

If you have a public client that is unable to use registered client secrets or an application running in a browser or on a mobile device, you must use the OAuth PKCE flow. You should also choose the OAuth PKCE flow if you have a native desktop application, a single-page web application, or a mobile application. Refresh tokens expire after 90 days using the OAuth PKCE flow and you don't have to store the client_secret.

You can determine which OAuth flow to use by answering the following questions:

  • Are you building a server application where you control the hosting? If yes, use the OAuth code flow.
  • Are you building a single-purpose application where the application needs an access token? If yes, use the PKCE flow and use a short-lived token.
  • Are you building a mobile application for installation on mobile devices around the world? If yes, use the PKCE flow and use a short-lived token.

Important

You cannot mix and match OAuth flows; you must choose either the code flow or the PKCE flow end to end.

To learn how to set up a basic website that uses the OAuth code flow, see OAuth Walkthrough: Test Authorization with a Web Server. For more information about writing authentication code, see OAuth Best Practices.

Link to section

Requirements and limitations

  • 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 obtained using the code flow don't expire. Refresh tokens obtained using the PKCE flow are single-use tokens and expire after 90 days. 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 obtained using the code flow 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.

Link to section

Webhooks

A webhook is a subscription that notifies you when a Square event occurs. For more information about using webhooks, see Square Webhooks Overview.

The OAuth API supports the following webhook event:

EventPermissionDescription
oauth.authorization.revokedN/ANotifies 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 Reference.

Link to section

Common errors

Authorization errors are typically caused by typos or mismatched credentials (Sandbox versus Production credentials).

  • Make sure you've updated placeholders and default values in the sample code with valid application credentials.
  • Make sure you've configured your credentials correctly. For example, if you're testing calls in production, make sure you're not using Sandbox credentials.
  • Make sure you're using the right credential type. For example, application IDs are used for OAuth API calls but access tokens are often used in other API calls.
  • For REST calls, make sure you've set the Authorization header key to Bearer and a valid access token.
Link to section

See also