OAuth API

How OAuth Works

To integrate your application with Square and use OAuth, start by registering your application in the Developer Dashboard. When you use the OAuth flow, your application gets access to Square account resources after the Square account owner authorizes the requested permissions. The following kinds of access can be granted:

  • Call Square APIs on behalf of a seller.

  • Use webhooks to receive notifications about changes to a seller's resources.

  • Take payments and collect payment application fees on behalf of a seller.

Access permissions Permalink Get a link to this section

Your application lets the seller authorize requested permissions by sending the seller to the Square authorization page which then returns authorization code to your application. The code is passed to the ObtainToken and access and refresh tokens are returned. An access token expires in 30 days. An authorization code can only be used once and expires in five minutes.

The OAuth API also lets an application refresh or revoke permissions. To maintain access after 30 days, your application gets a new access token by calling ObtainToken and providing a refresh token instead of the authorization code.

Permissions can be revoked in two ways:

  • The authorizing seller can revoke access through the My Applications page in the Square Seller Dashboard. This revokes all permissions to the seller's resources and invalidates all the access tokens and the refresh token.

  • Your application calls RevokeToken to revoke all permissions for your application. This action invalidates all access tokens and the refresh token. By setting a request parameter, your application can revoke a single access token instead of the whole set. This leaves other access tokens usable.

Authorizing an application and obtaining access tokens Permalink Get a link to this section

Your application starts the OAuth flow by rendering a link to send the seller to the Square authorization page where they sign in to Square and authorize requested permissions. These permissions and your application ID are query parameters in the authorize URL. For a list of all permissions that can be requested, see OAuth Permissions Reference. These permissions are known as scopes in the OAuth specification.

After you find the permissions needed by your application, form a URL encoded link to the Square authorization page. Separate the items in the permissions list with %20 or + characters. The link's URL looks like this:

https://connect.squareupsandbox.com/oauth2/authorize?client_id={YOUR_SANDBOX_APP_ID}&scope=CUSTOMERS_WRITE+CUSTOMERS_READ&state=82201dd8d83d23cc8a48caf52ba4f4fb

Replace {YOUR_SANDBOX_APP_ID} with your actual sandbox application ID in the Developer Dashboard. Refer to the OAuth Permissions Reference. to learn which Square API endpoints are enabled by CUSTOMERS_WRITE+CUSTOMERS_READ. For information about using the OAuth API in production, see OAuth API Best Practices.

Note

These examples use the Square Sandbox. The base domain is the Sandbox domain https://connect.squareupsandbox.com instead of the Production domain of https://connect.squareup.com.

Place the link on a web page or within your application at a point where you want the seller to sign into Square and authorize your application to access their account. When the seller follows the link, they see a page that looks like the following:

OAuth : How it works : fig 1

The Square authorization page displays the permissions to authorize and lets the seller choose to allow or deny those permissions. After the seller accepts or denies the permissions, the page redirects to the URL specified in the Sandbox Redirect URL box on the OAuth page for your application in the Developer Dashboard.

Your web page that handles the authorization redirect needs to handle the Allow or Deny responses in the query string. If the seller chooses Allow, the redirect URL looks like the following:

http://localhost:8000/sandbox_callback.php?code=sandbox-sq0cgb-79o-W0t3DFZEyy1wzv0WTw&response_type=code#_=_

The code parameter is the authorization code that you exchange for an access token for this seller.

If the seller chooses Deny, the redirect URL looks like the following:

http://localhost:8000/sandbox_callback.php?error=access_denied&error_description=user_denied#_=_

Note

These examples use the Square Sandbox and redirect to http://localhost. In production you must set your redirect page on your web server and use the HTTPS scheme.

After you get the authorization code, call the ObtainToken endpoint with the code to get the seller's OAuth access token. The authorization code expires 5 minutes after the Square authorization page generates the code. If the code expires before you get an access token, the seller must go to the authorization page again to get another authorization code.

An ObtainToken call looks like the following example:

Obtain Token
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
curl https://connect.squareupsandbox.com/oauth2/token \
  -X POST \
  -H 'Square-Version: 2021-05-13' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "sandbox-APPLICATION_ID_EXAMPLE",
    "client_secret": "sandbox-sq0csb-APPLICATION_SECRET_EXAMPLE",
    "code": "sandbox-AUTHORIZATION_CODE_EXAMPLE",
    "grant_type": "authorization_code"
  }'

The client_id value is the application ID and the client_secret is the application secret on the OAuth page in the Developer Dashboard. The code parameter is the authorization code passed back to the redirect URL by the Square authorization page. The response looks like the following:

{
  "access_token": "{EXAMPLE_OAUTH_ACCESS_TOKEN}",
  "token_type": "bearer",
  "expires_at": "2020-05-15T19:36:00Z",
  "merchant_id": "{MERCHANT_ID}",
  "refresh_token": "{EXAMPLE_OAUTH_REFRESH_TOKEN}"
}

The access_token value is the OAuth access token for the seller. You use the access token to call the Square API endpoints for which you have been granted permission. The access token has a limited lifetime of 30 days and the expires_at value is the expiry date/time. The refresh_token enables you to get a new OAuth token to replace a token that has expired or is about to expire. Refresh tokens do not expire. You can call the ObtainToken endpoint with a refresh token at any time.

Important

Store OAuth access and refresh tokens securely. A client-side application should never store or interact with OAuth tokens. Your application should make Square API calls on the server side. OAuth tokens should be stored encrypted and should never be stored in plaintext.
Access and refresh tokens must be stored together as a pair. If your application has stored a pair of tokens from a previous seller authorization flow, you must replace both of the old tokens with the new access and refresh tokens.

Use a refresh token to get a new OAuth token Permalink Get a link to this section

OAuth access tokens expire 30 days after they are issued, but refresh tokens do not expire. When an access token expires, you send a request to the ObtainToken endpoint, include the refresh token in the request body, and set the grant_type to refresh_token. If your request succeeds, the ObtainToken endpoint returns a new access token. See Refresh an expiring OAuth access token to learn how to refresh an access token.

You can reduce the scope of access permissions granted to your application when you request a new access token using a refresh token. When the access scoped is reduced in this way, the seller is not forced to sign in to Square and authorize the reduced scope. To learn about scope reduction, see Get Right-Sized Permissions with Down-Scoped OAuth Tokens.

Revoking access tokens for an application Permalink Get a link to this section

Your application can have its access completely revoked in two ways:

  • The seller can disconnect the application through My Applications page in the Seller Dashboard. Disconnecting an application calls RevokeToken to revoke all OAuth tokens for the seller. This includes all your application's access tokens and refresh tokens for that particular seller.

  • Your application can directly call RevokeToken to revoke all tokens for your application for a particular seller. This is effectively the same as the seller disconnecting your application.

See Revoke OAuth access tokens to learn how to revoke access tokens for an application.