Applies to: OAuth API
Learn how to register your redirect URL and build the authorization URL that directs sellers to the authorization page.
Applications use an OAuth access token to call Square APIs on behalf of a Square seller. Before you can obtain access tokens, you must set up two URLs:
Redirect URL - Your application endpoint that receives the authorization response from Square.
Authorization URL - The URL that sends sellers to the Square authorization page where they can grant permissions to your application. You append parameters to the URL and provide it as a link or button from your application, web page, email, or automated response.
After a seller grants permissions, Square appends an authorization code and other response parameters to your redirect URL and redirects the seller back to your application.
The redirect URL is the endpoint where your application or web page receives authorization responses from Square.
The following requirements apply for the production environment:
- Your redirect endpoint must use HTTPS. This is also a requirement for the Square Sandbox environment.
- Your endpoint must be able to process the
GETauthorization response and securely store the access and refresh tokens and thecode_verifierif you're using the PKCE flow. For more information, see Receive Seller Authorization and Manage Seller OAuth Tokens. - When Square redirects the seller back to your endpoint with the authorization response, you must display a user-friendly message indicating that the approval or denial was successfully processed.
To register your redirect URL and get your application credentials:
Sign in to the Developer Console and choose Open for your application. If needed, you can add an application from the Applications page.
At the top of the page, choose the Sandbox (for testing) or Production environment.
In the left pane, choose OAuth.
Register your redirect URL:
- In the Redirect URL box, choose Update, and then enter your exact redirect URL.
- Choose Confirm.
Note
Mobile and desktop clients using the PKCE flow can use dynamic ports.
Copy your application credentials to use later in the OAuth process:
- In the Application ID box, copy the application ID.
- In the Application Secret box, choose Show, and then copy the application secret. The application secret is only used in the code flow.
Mobile and desktop clients that use the PKCE flow can dynamically define ports for the redirect URL at runtime. To use this feature, complete these steps:
In the Developer Console, register the redirect URL using the literal "<port>" in place of the port number. For example:
- https://my-app:<port>/callback
- http://localhost:<port>
In the authorization URL, specify the full redirect URL with the port number in the
redirect_uriparameter.
The authorization URL directs sellers to the Square authorization page where they can grant permissions to your application. You build the authorization URL by appending parameters such as client_id and the permissions scope, as shown in the following example:
https://connect.squareup.com/oauth2/authorize?client_id=sq0idp-LJ1Sr4Iim0hGGvsMrx83vF&scope=CUSTOMERS_WRITE+CUSTOMERS_READ&session=false&state=W4gMTIzNDU2N219deiBzYWd2Fp33z
The code flow and PKCE flow use different sets of authorization URL parameters.
Production
https://connect.squareup.com/oauth2/authorize ?client_id=sq0idp-LJ1Sr4Iim0hGGvsMrx83vF // your production application ID &scope=CUSTOMERS_WRITE+CUSTOMERS_READ // requested permissions &session=false // false for production apps &state=W4gMTIzNDU2N219deiBzYWd2Fp33z // CSRF tokenSandbox - for testing only
https://connect.squareupsandbox.com/oauth2/authorize ?client_id=sandbox-sq0idb-ioiyW39PwrXoGyLt4 // your Sandbox application ID &scope=CUSTOMERS_WRITE+CUSTOMERS_READ // requested permissions &state=c2hvcnRfdG9rZW4x23SYc8a48hbXBsZ // CSRF tokenLine breaks and comments in the examples are added for clarity.
Important
Make sure to provide sellers with the authorization URL for the production environment, which uses the production base URL and your production application ID.
The following parameters can be used in the authorization URL for the code flow, PKCE flow, or both.
| Parameter | Description | Flow |
|---|---|---|
| Your application ID, obtained from the OAuth page in the Developer Console. Make sure to use the correct application ID that corresponds to the production or Sandbox environment. | Code, PKCE |
| A list of the OAuth permissions to request from the seller, separated by a space or the To align with the "least privilege" best practice, request only the permissions that your application requires. For more information, see Set the scope parameter. | Code, PKCE |
| Specifies whether sellers must log in to the Square authorization page. For a production application, this parameter must be set to | Code, PKCE |
| A cross-site request forgery (CSRF) token, which is a unique, random, and unpredictable string generated by your application server. Square returns this token in the This technique helps mitigate CSRF attacks. For more information, see section 10.2 of the OAuth 2.0 protocol specification (RFC 6749). | Code, PKCE |
| A Base64 URL-encoded SHA256 hash of the code verifier, which is a unique, random, client-generated string your application provides in the Including this parameter indicates that you're using the PKCE flow and requires that you include | PKCE |
redirect_uri | The redirect URL, which is required when using dynamic ports. | PKCE |
| Optional. Forces the Square authorization page to display using a particular locale. Square detects the locale automatically, so only provide this parameter if your application can definitively determine the preferred locale and has a specific reason for doing so. Supported values are | Code, PKCE |
Note
Square also accepts response_type=code, but you can omit it because only code is supported and it's the default value. The token response type isn't supported.
The scope parameter lists the permissions your application is requesting from sellers. As a best practice, follow the least privilege principle and request only the permissions that your application requires. You can find required permissions for each endpoint in the Square API Reference and OAuth Permissions Reference.
For example, suppose you're building a simple invoicing application that processes payments and refunds, displays payment information to customers and sellers, and collects an application fee from payments. You need the following permissions:
PAYMENTS_WRITE- Required for CreatePayment and RefundPayment.PAYMENTS_READ- Required for ListPayments and GetPayment.PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS- Required forCreatePaymentif you collect an application fee.
Some endpoints might require multiple permissions and others require permissions for specific access, such as PayOrder or ListBookings.
Note
While it's important not to request more permissions than necessary, also consider permissions needed for future integrations and new features. If your application evolves to include new features or integrates with other systems that require additional permissions, you must request these permissions through a new authorization request to the seller.
You should explicitly specify the permissions that your application requires. If you don't set a scope (not recommended), the default permission scope is:
MERCHANT_PROFILE_READPAYMENTS_READBANK_ACCOUNTS_READSETTLEMENTS_READ
Note that you cannot find which permissions are associated with an authorization code before you call ObtainToken. However, you can call RetrieveTokenStatus to get the permissions associated with an access token.