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.
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_verifierif you're using the PKCE flow.
To get your application credentials and set the redirect URL:
- Sign in to the Developer Dashboard.
- Choose Open for your production application. If you don't have an application set up, see Get Started.
- At the top of the page, set the mode to Production.
- In the left pane, choose OAuth.
- In the Application ID box, copy and save the application ID for use in the next section.
- In the Application Secret box, choose Show, and then copy and save the application secret for use in the next section.
- In the Redirect URL box, enter the URL that redirects the seller authorization to your production application.
- Choose Save.
The PKCE flow supports dynamic ports to create a redirect URL at runtime for mobile and desktop clients:
- Add the literal <
port> as a placeholder for a port in the Redirect URL box in the Developer Dashboard (for example,
- Pass in the actual port in the
redirect_urlfield for the Authorize endpoint. For example:
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:
The URL includes the following:
- Your application ID - In the URL, this is the
- A list of permissions you want the seller to grant to your application - In the URL, this is the
&scopeparameter. 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
&sessionparameter. This parameter determines whether a seller must log in to the Square authorization page. For a production application, this parameter must be set to
falseso 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
&stateparameter. This parameter is a string that's 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
&stateparameter is returned to your application's redirect URL, your application should verify the authenticity of the
&statevalue. 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's generated by the client and is a string value encrypted using SHA-256 encryption.
response_type- (optional) In the URL, this is the
&response_typeparameter. This parameter is required by the OAuth 2.0 protocol, but its value defaults to
codeso you don't need to specify it. The
codevalue specifies that the authorization response includes a
codeparameter containing the authorization code. The
tokenvalue is no longer supported.
locale- (optional) In the URL, this is the
&localeparameter. You can optionally pass a
localeparameter 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.
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're 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:
The last permission is required for
CreatePayment calls if your application takes an application fee that's paid into your developer account. Some specific variations of a call require more permissions. Some calls, such as
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 don't 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 don't set a scope (not recommended), the default is as follows:
However, you shouldn't rely on the default scope. You should explicitly set the scope that your application requires.