OAuth API

Best Practices

After completing the OAuth walkthrough, you should have a good understanding of the OAuth workflow and how to implement it in the Square Sandbox. To build for production, there are some best practices you should follow for your Square integration. If you plan to build an application for the App Marketplace, you must follow these best practices for your application submission to be accepted.

Account for differences between production and the Square Sandbox
Permalink Get a link to this section

The following differences between production and the Square Sandbox include:

  • Your application must use HTTPS in production. For testing, you can use localhost and HTTP.

  • In production, the session parameter for the authorization page URL should be set to false. However, the Square Sandbox supports only true.

  • In the Sandbox, the application ID has a prefix of sandbox at the beginning of the ID.

  • In the Sandbox, the application secret has a prefix of sandbox.

  • Sandbox and production endpoints have different base URLs:

    • Sandbox: https://connect.squareupsandbox.com

    • Production: https://connect.squareup.com

    Make sure you are using your production ID, secret, and base URL when implementing and running in production.

Pass appropriate parameters to the Square authorization page
Permalink Get a link to this section

The client_id is required. Make sure you are passing your application's production application ID.

In addition to the client_id parameter, set the following parameters:

scope
Permalink Get a link to this section

Set 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.

For example, suppose you are building a basic invoicing application that accepts payments from customers on behalf of sellers ( Create Payment), displays payments for customers and sellers ( List Payments and Get Payment), processes refunds ( Refund Payment), and takes an application fee on payments. You need to the following permissions:

  • PAYMENTS_WRITE

  • PAYMENTS_READ

  • PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS

The last permission is required on Create Payment calls if your application takes an application fee that is paid into your developer account. Some specific variations of a call require more permissions. Some calls such as Pay Order (ORDERS_WRITE and PAYMENTS_WRITE) require multiple permissions. Each endpoint in the Square API Reference lists the permissions required to call it. The Permissions Reference lists all the permissions and the APIs and endpoints they apply to.

If you added any other permissions beyond what your application needs, you need to remove those permissions before submitting your application to the App Marketplace.

If you do not set a scope (not recommended), the default is the following:

  • MERCHANT_PROFILE_READ

  • PAYMENTS_READ

  • SETTLEMENTS_READ

  • BANK_ACCOUNTS_READ

    However, you should not rely on the default scope. You should explicitly set the scope that your application requires.

session
Permalink Get a link to this section

Set session to false. The session parameter tells the Square authorization page to use the seller's logged in Square session without having to explicitly log in. Your application should set session to false to force the seller to log in. Many sellers have multiple Square accounts. This helps ensure that the seller is authorizing your application for the correct Square account.

Note that the default is true so you must explicitly set the session parameter to false.

state
Permalink Get a link to this section

Set state to a cross-site request forgery (CSRF) token. The state parameter is a string that is passed to the Square authorization page and returned as a state parameter to the callback defined for your application. A CSRF token is a unique, random, and unpredictable value generated by your application server. When the state parameter is returned to your application's callback, your application should verify the authenticity of the state value. This technique helps mitigate CSRF attacks. For more information, see section 10.2 of the OAuth 2.0 Protocol specification (RFC 6749).

Other optional parameters
Permalink Get a link to this section

response_type. The response_type parameter is actually required but it defaults to code so you do not need to specify it. The code value specifies that the callback receives a code parameter containing the authorization code. The Square OAuth API does not support implicit grants; therefore, specifying response_type as token returns an error.

locale. You can optionally pass a locale parameter 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 it has a specific reason for doing so.

Custom parameters (any parameters not defined in this section) are not passed back to the application's redirect URL.

Handle parameters in the callback
Permalink Get a link to this section

The Square authorization page can return two forms of parameters to your application's callback URL: authorization allowed and errors.

Handling authorization allowed
Permalink Get a link to this section

When the seller chooses Allow on the Square authorization page, it redirects to your application's callback page with a URL that looks like the following:

https://example.com/callback.php?code=sq0cgb-xJPZ8rwCk7KfapZz815Grw&response_type=code&state=jf0weoif3dfsk04imofpdgmlksadfwmvmf4oip

The URL returns the following parameters:

  • state is the CSRF token your application passed in the state parameter for the Square authorization page. Use this value to verify this is a valid request.

  • response_type is code. This signals that an authorization code was returned.

  • code is the authorization code that you use to call Obtain Token.

Handling errors
Permalink Get a link to this section

When there is an error, the callback URL returns the following parameters:

  • state is the CSRF token your application passed in the state parameter for the Square authorization page.

  • error is the error type.

  • error_description provides more details about the error.

Choosing the Deny button is an error case. When the seller chooses Deny on the Square authorization page, it redirects to your application's callback page with a URL that looks like the following:

    http://example.com/callback.php?error=access_denied&error_description=user_denied&state=59192b1e9f3c448569e0008b6856da50#_=_

The error value of access_denied indicates that authorization was denied. The error_description indicates that the reason for the denial was because the user clicked the Deny button.

Manage, use, and store tokens securely
Permalink Get a link to this section

OAuth and refresh tokens as well as the application secret have privileged access (or potential to get privileged access) to seller resources. You should use them in a secure environment and protect access to them. Follow these best practices:

  • OAuth operations should be performed on a secure application server. This includes, for example, calls to Obtain Token to obtain the original OAuth and refresh tokens, subsequent calls to get a new OAuth access token using a refresh token, generating and validating the state parameter, encrypting the tokens and application secret, and revoking a token. Do not store or use OAuth or refresh tokens on web or mobile clients.

  • OAuth and refresh tokens should be stored encrypted in a secure database. Your application should use a strong encryption standard such as AES. The production encryption keys should not be accessible to database administrators, business analysts, developers, or anyone who does not need them. The tokens that these keys protect can be used to perform actions on behalf of the seller and should be guarded appropriately. The encryption keys should not be stored in source control and only be accessible by server administrators.

Ensure tokens are valid
Permalink Get a link to this section

Submitting an API request without a valid OAuth access token results in a poor experience for sellers and potentially their customers. In some cases, a seller might be prevented from taking payments. An OAuth access token can be invalid for two main reasons: expiration and revocation.

Expiration
Permalink Get a link to this section

An OAuth access token expires after 30 days. If your application does not get a new access token, it cannot make calls on behalf of the seller. This can happen if your application does not have a token refresh process, but it can also happen if the call to Obtain Token fails and your application does not detect the failure and does not retry.

To ensure tokens remain in a valid state, Square requires all partner applications to renew at a frequent interval.

Recommendations

  1. Your application must automatically renew OAuth access tokens every seven days or less, regardless of whether the seller is actively interacting with your application. Renewing every seven days or less provides sufficient time to discover and resolve errors. If your application only attempts to refresh tokens near the 30-day expiration date, it increases the risk of missing a failed token refresh and creating a poor experience for sellers or their customers.

  2. Your application should check tokens when they are retrieved from your database to see whether they are older than eight days. If this check fails, it should generate a notification (paging or other alerting mechanism) so that you can address any issues with your renewal logic. Silent token renewal failures result in breaking your application integration and potentially cause an outage for your sellers or their customers.

Revocation
Permalink Get a link to this section

An OAuth access token can be 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.

  • Your application can call Revoke Token to revoke a particular OAuth token or all OAuth tokens for a seller account.

Recommendation

To ensure a token is valid and not revoked, make a call to List Locations and check the response to confirm validity.

Show token status to sellers and enable them to manage authorization
Permalink Get a link to this section

Your application must provide a mechanism for sellers to view the status of their connection with Square (OAuth access token status) and to manage the authorization for your application. Typically, this would be a settings/configuration dashboard in your application.

Recommendations

  • Your application must accurately show the seller's correct OAuth access token status with Square. OAuth access token status must always be accurate and indicate the correct state of the access token (valid, expired, or revoked). Using the recommendation method in the previous section, your application can check the validity of the token by calling List Locations and checking the response.

  • Your application must enable the seller to disconnect by revoking the access token. You revoke access tokens using Revoke Token.

Ensure API calls made with OAuth tokens handle token-based errors appropriately
Permalink Get a link to this section

When your application uses an OAuth access token to make a call, OAuth-related errors can occur if a token is expired, revoked, or has insufficient scope (unauthorized). Your application should handle these error codes and display a customer-friendly message that clearly communicates the error to the seller, their customer, or both:

  • ACCESS_TOKEN_EXPIRED

  • ACCESS_TOKEN_REVOKED

  • UNAUTHORIZED