OAuth API

How OAuth Works

To build an application that integrates with Square, you start by creating a Square application in the Developer Dashboard. When you implement the OAuth flow for a Square application, you have the following capabilities based on the permissions granted by the owner of a seller account:

  • Call Square APIs on behalf of a seller to manage the seller's resources.

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

  • Take payments on behalf of a seller and collect an application fee on those payments.

By implementing the OAuth 2.0 protocol, the Square OAuth API lets an application request and obtain permission from a Square seller account to make API calls on behalf of that account. Your application does this using the Square authorization page to get an authorization code and calling Obtain Token to exchange that code for an access token and refresh token. Access tokens expire after 30 days.

The OAuth API also enables an application to renew and revoke application permissions. To maintain access, your application gets a new OAuth access token by calling Obtain Token but passing the refresh token instead of the authorization code. Access can be revoked two ways:

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

  • Your application can call the Revoke Token endpoint to completely revoke all permissions for your application, meaning all access tokens and the refresh token. It can also just revoke a single access token.

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

The first part of the OAuth flow is creating a link that sends the seller account owner to the Square authorization page so the seller's identity can be verified using Square sign-in and that the owner can grant permissions to your application. The requested permissions and the application ID are passed in the query parameters of the link. For the complete list of permissions, see Square API OAuth Permissions Reference . For example, your application needs the CUSTOMERS_WRITE permission to call the following Customers API endpoints:

If you are familiar with OAuth, these permissions are called scopes in the OAuth specification.

After you determine the permissions your application needs, you create the link to the Square authorization page. The link must be URL encoded: Separate the items in the permissions list with %20 or the + character. The link's URL looks like this:

https://connect.squareupsandbox.com/oauth2/authorize?client_id=sandbox-sq0idb-v1ByH-0zwEy1Wgp_WmZfaA&scope=CUSTOMERS_WRITE+CUSTOMERS_READ&state=82201dd8d83d23cc8a48caf52ba4f4fb

Theclient_id parameter is the ID for your application in the Developer Dashboard. The scope parameter is the list of permissions to grant. In addition to the CUSTOMER_WRITE permission that enables access to the endpoints previously listed, the scope includes the CUSTOMERS_READ permission providing access to the following additional endpoints:

Note These examples use the Square Sandbox. The base URL is a Sandbox URL https://connect.squareupsandbox.com instead of a production URL https://connect.squareup.com. The client_id also has a Sandbox prefix. For information about using the OAuth API in production, see OAuth Production Best Practices .

You place the link on a web page or within your application during the setup process or at a point where you want the seller to authorize your application to access their account. When the seller follows the link, the seller sees a page that looks like the following:

OAuth : How it works : fig 1

The Square authorization page displays the permissions to grant and enables the seller to allow or deny those permissions for your application. After the seller chooses one of the two buttons, the page redirects to the URL specified in the Sandbox Redirect URL box on the OAuth page for your application in the Developer Dashboard.

OAuth API : How it works : figure 2

The page on your web server specified in the Sandbox Redirect URL box needs to handle the Allow and 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 test with localhost and HTTP. You can use HTTP for testing with localhost; however, you must use HTTPS when using a web server.

After you get the authorization code, you call the Obtain Token endpoint to exchange the code for the seller's OAuth access token. Note that the authorization code expires five minutes after the Square authorization page generates the code. If the code expires, you must have the seller authorize through the authorization page again.

An Obtain Token call looks like the following using cURL:

curl https://connect.squareupsandbox.com/oauth2/token \
  -X POST \
  -H 'Square-Version: 2020-03-25' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "sandbox-sq0idb-v1ByH-0zwEy1Wgp_WmZfaA",
    "client_secret": "sandbox-sq0csb-APPLICATION_SECRET_EXAMPLE",
    "code": "sandbox-sq0cgb-79o-W0t3DFZEyy1wzv0WTw",
    "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": "EAAAEL_l5ncx260W8yWz2gGO0GtJeFBJqIdHIXZjpQZ_XW-yxh-Tl7MlF8vIE__n",
  "token_type": "bearer",
  "expires_at": "2020-05-15T19:36:00Z",
  "merchant_id": "TVSNN09QQY609",
  "refresh_token": "EQAAEInZRUFx8bgauwrDjXYIioyCDEB7vyOG0cScx-qfczgTpNtUjAGLResAKOe9"
}

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 Obtain Token endpoint with a refresh token at any time.

Important

Store OAuth access and refresh tokens securely . 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.

Getting a new OAuth token using the refresh 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 Obtain Token endpoint, include the refresh token in the request body, and set the grant_type to refresh_token. If your request succeeds, the Obtain Token endpoint returns a new access token.

The following cURL command calls Obtain Token with a refresh token:

curl https://connect.squareupsandbox.com/oauth2/token \
  -X POST \
  -H 'Square-Version: 2020-04-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "refresh_token": "EQAAEIVtJhvQ9L2ieKdN3d9f39w-rFSY1iBZ2FO-pKzAMpQkQHGWsPVwAhgX7uAJ",
    "client_id": "sandbox-sq0idb-v1ByH-0zwEy1Wgp_WmZfaA",
    "client_secret": "sandbox-sq0csb-APPLICATION_SECRET_EXAMPLE",
    "grant_type": "refresh_token"
  }'

The response looks like the following:

{
  "access_token": "EAAAECgRC5zBNyYOMehVGml0Fe9B9ybG9hPXfmN1_dEZIh4WdNdDACm0_fJI9tGL",
  "token_type": "bearer",
  "expires_at": "2020-06-06T02:17:22Z",
  "merchant_id": "MYC75QZZT9DNW",
  "refresh_token": "EQAAEIVtJhvQ9L2ieKdN3d9f39w-rFSY1iBZ2FO-pKzAMpQkQHGWsPVwAhgX7uAJ"
}

Revoking access 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 in the Seller Dashboard. Disconnecting an application calls Revoke Token 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 Revoke Token to revoke all tokens for your application for a particular seller. This is effectively the same as the seller disconnecting your application.

The following cURL command calls Revoke Token and specifies an access token you obtained from the seller:

curl https://connect.squareupsandbox.com/oauth2/revoke \
  -X POST \
  -H 'Square-Version: 2020-04-22' \
  -H 'Authorization: Client sandbox-sq0csb-APPLICATION_SECRET_EXAMPLE' \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "EAAAENcWuhrWwJ0njn7RxCHhAppPpzfm4_Txg6JOP-YjsjTn4fLEAvw7TjG_wiEE",
    "client_id": "sandbox-sq0idb-v1ByH-0zwEy1Wgp_WmZfaA",
    "revoke_only_access_token": false
  }'

Note that the Revoke Token call requires an Authorization header that is the word Client separated by space from the application secret. Obtain Token does not require an Authorization header and puts the client secret in the body instead. The access_token value is the OAuth token to revoke and client_id is the application ID. The revoke_only_access_token specifies whether only this access token is revoked or all tokens including the refresh token are revoked. Because the default is false, you can omit this parameter in this case. If the call succeeds, your application gets a response that looks like the following:

{
  "success": true
}

Revoking only a single access token Permalink Get a link to this section

Your application can also revoke a particular OAuth access token for a seller, but leave other tokens intact. By calling Revoke Token with revoke_only_access_token set to true, your application revokes only the specified access token but leaves all other access tokens and the refresh token for that seller intact. The following cURL command revokes only the specified access token:

curl https://connect.squareupsandbox.com/oauth2/revoke \
  -X POST \
  -H 'Square-Version: 2020-04-22' \
  -H 'Authorization: Client sandbox-sq0csb-APPLICATION_SECRET_EXAMPLE' \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "EAAAELbH71eIbkb8K8mbJGoDqW6ZEfAgIBSMY1N-sJ7Y0QhmqnP1x7mN7wVBSqFq
",
    "client_id": "sandbox-sq0idb-v1ByH-0zwEy1Wgp_WmZfaA",
    "revoke_only_access_token": true
  }'

Note that this call is the same as the previous call that revoked all tokens except that revoke_only_access_token is set to true.