OAuth Best Practices

Applies to: OAuth API | Locations API

Learn about best practices for using the OAuth API to authorize your application to access a Square account.

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.

The following video provides an introduction to OAuth best practices. For an in-depth discussion of OAuth best practices, see the following sections.

Square supports two OAuth processes: a code flow and PKCE flow. The code flow is the process where clients obtain an authorization code that's then redeemed to get an access token and refresh token. When redeeming the authorization code, the client must pass in a client_id and client_secret. This is the best process for applications with confidential clients that connect to secure backend servers.

The PKCE flow follows a similar process to the code flow, but removes the need to pass in the client_secret when redeeming the authorization code. This makes the PKCE flow ideal for mobile applications and applications with public clients, such as single-page websites and applications that rely on a web browser.

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.

To retrieve the permissions attached with the access token later, you can call the RetrieveTokenStatus endpoint with the access token.

If you add features to your application or integrate with other systems that require additional permissions, you must ask for those permissions with a new authorization request to the seller. Though you don't want to request more permissions than you need, you must consider what permissions you need for future integrations or for additional features that your application might support in the future. Your application should have a process where the seller can approve additional permissions in addition to the permissions already authorized.

OAuth access tokens, refresh tokens, and the application secret all 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 that use a private client should be performed on a secure application server. This includes, for example, calls to ObtainToken to obtain the original OAuth access token and refresh token, 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.
• Never store the application secret, access token, or refresh token in a mobile application or on any public client. Use the PKCE flow for these scenarios.
• OAuth access tokens and refresh tokens should be stored encrypted in a secure database or keychain. Your application should use a strong encryption standard such as AES. The production encryption keys shouldn't be accessible to database administrators, business analysts, developers, or anyone who doesn't 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 shouldn't be stored in source control and should only be accessible by server administrators.
• When you request authorization from a seller, record the permissions that you request. After the seller authorizes your request and you receive the authorization code, you cannot find what permissions are associated with the code or the access token you receive when you call ObtainToken.

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.

An OAuth access token expires after 30 days. If your application doesn't get a new access token, it cannot make calls on behalf of the seller. This can happen if your application doesn't have a token refresh process, but it can also happen if the call to ObtainToken fails and your application doesn't detect the failure and doesn't retry. For more information about refreshing access tokens, see Refresh, Revoke, and Limit the Scope of OAuth Tokens.

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're retrieved from your database to see whether they're 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.

Refresh tokens used with PKCE are single-use tokens and expire in 90 days.

An OAuth access token can be revoked in two ways:

• The seller can disconnect the application through My Applications in the Square Dashboard. Disconnecting an application calls RevokeToken to revoke all OAuth tokens for the seller.
• Your application can call RevokeToken to revoke a particular OAuth token or all OAuth tokens for a seller account.

To ensure that a token is valid and not revoked, call ListLocations and check the response to confirm validity.

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 can revoke OAuth access tokens by calling RevokeToken.

When your application uses an access token to call a Square API, OAuth-related errors can occur if a token is expired, is 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. Errors include:

• ACCESS_TOKEN_EXPIRED
• ACCESS_TOKEN_REVOKED
• UNAUTHORIZED

Square retains expired access tokens for a limited time. During this time, the Square API returns the ACCESS_TOKEN_EXPIRED error. After that time, the Square API returns an UNAUTHORIZED error. Square API calls that return the UNAUTHORIZED error aren't cases of insufficient scope. Square API calls with insufficient scope return a 403 FORBIDDEN error.

• Create the Redirect URL and Square Authorization Page URL
• Receive Seller Authorization and Manage Seller OAuth Tokens
• Refresh, Revoke, and Limit the Scope of OAuth Tokens
• OAuth Walkthrough: Test Authorization with a Web Server
• Move OAuth from the Sandbox to Production
• OAuth Permissions Reference