OAuth API

Best Practices

Use the following best practices when creating an application that uses OAuth. These best practices are in addition to the basics of programming a functioning application that correctly manages OAuth tokens and handles permission errors successfully.

If you plan to build an application for the App Marketplace, see the list of requirements at App Marketplace API Usage Requirements.

Requested permissions (scope) Permalink Get a link to this section

When requesting authorization for permissions from the seller, set the scope to the least privileged permissions required for your application. Your application should only request permissions for APIs that your application calls. For more information about requesting permissions, see Create the Redirect URL and Square Authorization Page URL. For a list of permissions, see OAuth Permissions Reference.

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 the potential to get privileged access) to seller resources. You should use them in a secure environment and protect access to them using the following best practices:

  • OAuth operations should be performed on a secure application server. This includes, for example, calls to ObtainToken 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 encrypted and stored 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 should only be accessible by server administrators.

Warning

Never store your credentials or access tokens in your version control system. The .env file is included in the .gitignore project to help prevent uploading confidential information.

You should never put the application secret in your source code. Instead, encrypt the secret and use an environment variable to reference the secret in your application.

Refresh the access token regularly 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 ObtainToken fails and your application does not detect the failure and does not retry.

Your application should automatically renew OAuth access tokens every 7 days or less, regardless of whether the seller is actively interacting with your application. Renewing every 7 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.

Your application should check tokens when they are retrieved from your database to see whether they are older than 8 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 causing an outage for your sellers or their customers.

Show the OAuth 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 (the OAuth access tokens status) and manage the authorization for your application. Typically, this done with a settings/configuration dashboard in your application.

You should follow these practices:

  • 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 ListLocations and checking the response.

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

Related topics Permalink Get a link to this section