OAuth API

Applies to: OAuth API

Use the OAuth API to 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.

• 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.

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.

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.

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 Console 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 Console 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.

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.

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.

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.

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

The OAuth API supports the following webhook event:

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.

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.

• Create the Redirect URL and Square Authorization Page URL
• Receive Seller Authorization and Manage Seller OAuth Tokens
• Refresh, Revoke, and Limit the Scope of OAuth Tokens
• OAuth Walkthrough: Test Authorization with a Web Server
• OAuth Best Practices
• Move OAuth from the Sandbox to Production
• OAuth Permissions Reference
• Video: OAuth Best Practices