<- OAuth API

OAuth API

Authorize

GET

 /oauth2/authorize

As part of a URL sent to a seller to authorize permissions for the developer, Authorize displays an authorization page and a list of requested permissions.

The completed URL looks similar to the following example: https://connect.squareup.com/oauth2/authorize?client_id={YOUR_APP_ID}&scope=CUSTOMERS_WRITE+CUSTOMERS_READ&session=False&state=82201dd8d83d23cc8a48caf52b

The seller can approve or deny the permissions. If approved, Authorize returns an AuthorizeResponse that is sent to the redirect URL and includes a state string and an authorization code. The code is used in the ObtainToken call to obtain an access token and a refresh token that the developer uses to manage resources on behalf of the seller.

Important: The AuthorizeResponse is sent to the redirect URL that you set on the OAuth page of your application in the Developer Dashboard.

If an error occurs or the seller denies the request, Authorize returns an error response that includes error and error_description values. If the error is due to the seller denying the request, the error value is access_denied and the error_description is user_denied.

Link to section

Query parameters

Example code

Link to section

client_id

string

Required

The Square-issued ID for your application, which is available on the OAuth page for your application in the Developer Dashboard.

Link to section

scope

string

A space-separated list of the permissions that the application is requesting. Default: "MERCHANT_PROFILE_READ PAYMENTS_READ SETTLEMENTS_READ BANK_ACCOUNTS_READ"

Link to section

locale

string

The locale to present the permission request form in. Square detects the appropriate locale automatically. Only provide this value if the application can definitively determine the preferred locale.

Currently supported values: en-IE, en-US, en-CA, es-US, fr-CA, and ja-JP.

Link to section

session

boolean

If false, the user must log in to their Square account to view the Permission Request form, even if they already have a valid user session. This value has no effect in the Square Sandbox. Default: true

Link to section

state

string

When provided, state is passed to the configured redirect URL after the Permission Request form is submitted. You can include state and verify its value to help protect against cross-site request forgery.

Link to section

code_challenge

string

When provided, the OAuth flow uses PKCE to authorize. The code_challenge will be associated with the authorization_code and a code_verifier will need to passed in to obtain the access token.

Link to section

redirect_uri

string

The redirect URL assigned on the OAuth page for your application in the Developer Dashboard. This field is required to use a dynamic port at runtime (PKCE only). To use a dynamic port, use the literal "<port>" as a placeholder for a port in the Redirect URL box in the Developer Dashboard, for example, "http://localhost:<port>". When you call the Authorize endpoint from an application, pass in the actual port in this field. 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

Response fields

Link to section

code

string

A valid authorization code. Authorization codes are exchanged for OAuth access tokens with the ObtainToken endpoint.

Link to section

state

string

The same value specified in the request.