The first step in the OAuth process is to create a URL that requests permissions and directs the seller to the authorization page.
OAuth API

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 the 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 the PKCE flow.

To get your application credentials and set the redirect URL:

  1. Sign in to the Developer Dashboard.

  2. Choose Open for your production application. If you do not have an application set up, see Get Started.

  3. At the top of the page, set the mode to Production.

  4. In the left pane, choose OAuth.

  5. In the Application ID box, copy and save the application ID for use in the next section.

  6. In the Application Secret box, choose Show, and then copy and save the application secret for use in the next section.

  7. In the Redirect URL box, enter the URL that redirects the seller authorization to your production application.

  8. Choose Save.

Link to section
Use dynamic ports for PKCE redirect URLs

The PKCE flow supports dynamic ports to create a redirect URL at runtime for mobile and desktop clients:

  1. Add the literal <port> as a placeholder for a port in the Redirect URL box in the Developer Dashboard (for example, http://localhost:<port>).

  2. Pass in the actual port in the redirect_url field for the Authorize endpoint; for example, https://connect.squareup.com/oauth2/authorize?client_id={YOUR_APP_ID}&scope=MERCHANT_PROFILE_READ&redirect_uri=http://localhost:8000.

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>

Important

If you include code_challenge in the URL to the Authorize endpoint, you are committed to using the PKCE flow. This means you are required to pass in the code_verifier to the ObtainToken endpoint. If you do not include code_challenge in the URL to the Authorize endpoint, you are committed to using the code flow and you cannot include code_verifier in your request to the ObtainToken endpoint.

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. This 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 the 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.

Important

When you request authorization from a seller, record the permissions that you request. After the seller authorizes your request and you receive the authorization code, you cannot find what permissions are associated with the code or the access token you receive when you call ObtainToken.

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

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

On this page