Create the Redirect URL and Square Authorization Page URL

To begin the OAuth process, you need to create two URLs. The first is the redirect URL, which points to your OAuth application that receives the authorization response and that manages the seller’s access token, refresh token, and, in the case of PKCE flow, the code_verifier and its associated authorization code.

The second URL is the authorization URL, which you use to request permissions and to provide additional authorization information. This URL calls the Authorize endpoint, which allows the customer to approve your permissions request. You provide this URL to the seller who can grant the permissions you request. The response from this authorization page is sent to your redirect URL.

Link to section

Create the redirect URL

The redirect URL is the endpoint for your application or web page that processes the seller authorization response and manages the seller’s OAuth tokens. You need to add this URL to your application using the Developer Dashboard. The URL must exactly match the endpoint of your application that processes the seller authorization.

There are several requirements for a production redirect URL. These include:

• The URL must use HTTPS.

• The endpoint must be able to process the GET response from the seller's authorization through the Square authorization web page. This includes securely storing the access and refresh tokens and the code_verifier if you are using PKCE flow.

To get your application credentials and set the redirect URL:

Link to section

Create the authorization URL

To begin the process of having a seller authorize your application to act on their behalf, you first create the authorization URL with specific parameters. The code flow and PKCE flow processes have different parameters. The completed URL looks similar to the following examples:

Code flow https://connect.squareup.com/oauth2/authorize?client_id={YOUR_APP_ID}&scope=CUSTOMERS_WRITE+CUSTOMERS_READ&session=false&state=82201dd8d83d23cc8a48caf52b

PKCE flow https://connect.squareup.com/oauth2/authorize?client_id={YOUR_APP_ID}&scope=CUSTOMERS_WRITE+CUSTOMERS_READ&session=false&redirect_uri=<redirect_uri>&code_challenge=<code_challenge>

The URL includes the following:

• Your application ID. In the URL, this is the client_id parameter.

• A list of permissions you want the seller to grant to your application. In the URL, this is the &scope parameter. Your application should only request permissions for APIs that your application calls and should be the least privileged permissions required by your application. For more information about scoping your permissions request, see the following section.

• A Square session login parameter. In the URL, this is the &session parameter. The session parameter determines whether a seller must log in to the Square authorization page. For a production application, this parameter must be set to false so that the seller must log in. Many sellers have multiple Square accounts. Requiring the seller to log in helps ensure that the seller is authorizing your application for the correct Square account.

• A cross-site request forgery (CSRF) token. In the URL, this is the &state parameter. This parameter is a string that is passed to the Square authorization page and returned as a state parameter to the redirect URL defined for your application. A CSRF token is a unique, random, and unpredictable value generated by your application server. When the &state parameter is returned to your application's redirect URL, your application should verify the authenticity of the &state value. This technique helps mitigate CSRF attacks. For more information, see section 10.2 of the OAuth 2.0 protocol specification (RFC 6749).

• redirect_uri. This is the redirect URL. You can specify the URL in the request or set the value in the Developer Dashboard.

• code_challenge. This value is used with PKCE flow. It is generated by the client and is a string value encrypted using SHA-256 encryption.

• response_type. (optional) In the URL, this is the &response_type parameter. This parameter is required by the OAuth 2.0 protocol but its value defaults to code so you do not need to specify it. The code value specifies that the authorization response includes a code parameter containing the authorization code. The token value is no longer supported.

• locale. (optional) In the URL, this is the &locale parameter. You can optionally pass a locale parameter to force the Square authorization page to present the page using a particular locale. The Square authorization page detects the locale automatically, so this parameter should only be used if your application can definitively determine the preferred locale and has a specific reason for doing so.

You provide this URL to the seller. You can do so by creating the URL and sending it from your application, posting it on a web page, or providing it in an email or automated response. For more information about the authorization parameters, see Authorize.

Link to section

Set the scope parameter

Set the scope to the least privileged permissions required for your application. The scope parameter is the set of permissions that your application is requesting on the seller's account. Your application should only request permissions for APIs that your application calls and should use the least privileged permissions required. For a complete list of OAuth permissions, see OAuth Permissions Reference.

For example, suppose you are building a basic invoicing application that accepts payments from customers on behalf of the seller (CreatePayment), displays payments for customers and sellers (ListPayments and GetPayment), processes refunds (RefundPayment), and takes an application fee on payments. You need the following permissions:

• PAYMENTS_WRITE

• PAYMENTS_READ

• PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS

The last permission is required for CreatePayment calls if your application takes an application fee that is paid into your developer account. Some specific variations of a call require more permissions. Some calls, such as PayOrder (ORDERS_WRITE and PAYMENTS_WRITE), require multiple permissions. Each endpoint in the Square API Reference lists the permissions required to call it. The OAuth Permissions Reference lists all the permissions and the APIs and endpoints they apply to.

If you add features to your application or integrate with other systems that require additional permissions, you must ask for those permissions with a new authorization request to the seller. Though you do not want to request more permissions than you need, you must consider what permissions you need for future integrations or for additional features your application might support in the future.

If you do not set a scope (not recommended), the default is as follows:

• MERCHANT_PROFILE_READ

• PAYMENTS_READ

• SETTLEMENTS_READ

• BANK_ACCOUNTS_READ

However, you should not rely on the default scope. You should explicitly set the scope that your application requires.

Link to section

Related topics

• OAuth Overview

• Receive Seller Authorization and Manage Seller OAuth Tokens

• Refresh, Revoke, and Limit the Scope of OAuth Tokens

• OAuth Walkthrough: Authorization Using a Test Account

• Quick Walkthrough: Obtaining an Access Token in Sandbox

• OAuth Best Practices

• Move OAuth from the Sandbox to Production

• OAuth Permissions Reference

• Video: OAuth Best Practices