Move OAuth from the Sandbox to Production

Applies to: OAuth API

Learn how to move an application from the Square Sandbox to a production environment.

When your application that uses OAuth 2.0 to perform operations on behalf of Square seller accounts is ready for production, there are several tasks you must complete. These tasks are designed to strengthen the safety of the OAuth flow and give the seller a better sign-in experience. In addition, review the Square OAuth Best Practices before moving an application to production.

If your application relies on a public client, regardless of whether it's a mobile application, single-page web application, or relies on a web browser, you should use the PKCE flow. Public clients can be decompiled and credentials such as the client_secret can be easily obtained. The PKCE flow process doesn't rely on the client_secret being stored on the client. For more information, see PKCE flow.

A seller must have an account within the partner platform and have authenticated with that platform before being allowed to start the Square OAuth flow and authorize access to their Square account.

The following requirements ensure a secure authorization experience:

• Create a redirect URL for production that uses HTTPS. This should point to your OAuth application that receives the authorization response and that manages and stores OAuth tokens.
• Create a URL that you provide to the seller to access the Square authorization page, which grants you a set of permissions to use on the seller's behalf.
• Pass all needed parameters to the Square authorization page:

  • client_id - The client_id field must be set to the production application ID.

  • scope - The scope parameter is the permissions that your application is requesting for the seller's account. Only request permissions for APIs that your application calls. These are known as in-scope permissions. If the correct permissions aren't requested, API requests can fail with an INSUFFICIENT_SCOPES error. Make sure your application has the needed permissions before moving to production.

    An out-of-scope permission request is where the application is requesting permission for an API that isn't used. The returned access code gives too broad an access to a Square seller account, which can be a security risk. An example of an out-of-scope permission request is an application that lets a seller accept payments with the Square Web Payments SDK but doesn't create, update, or remove customers. The application is requesting CUSTOMERS_WRITE permission, which is an out-of-scope request.

  • session - The session parameter directs the Square authorization page to use the logged-in seller Square session, thereby removing the requirement to sign in to a Square account. Many sellers have multiple Square accounts and should be forced to sign in to one of them to ensure that they're authorizing your application for the correct Square account. Your application should set the session parameter to false to force the seller to sign in to one of their Square accounts.

  • state - The state parameter is a string that's passed to the Square authorization page and returned as a state parameter to the callback URL defined for your application. You can set the state value to a CSRF token that's 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 that the state value matches your generated CSRF token.

• Provide a user-friendly authorization failure page. If an OAuth flow is denied by the seller or another error occurs, your application should show a user-friendly page to tell them that authorization failed.

Be sure that your production application implements the following requirements for securely handling OAuth tokens:

• Don't store OAuth tokens on a public client - Access tokens must not be sent to or persisted on a native mobile client. Instead, store them securely on your application server. All methods involving OAuth should be managed by a service layer hosted by an application server.
• Require access token renewal - Square OAuth tokens expire every 30 days. To ensure that tokens remain valid, Square strongly recommends that all applications refresh their access tokens asynchronously every 7 days or less.
• Check for stale access tokens - Your production application should implement logic that checks the age of each token when retrieved from your database before being used in a Square API call. If a token is older than 8 days, your application should notify you that there's a problem with your renewal login. Avoid silent token failures, which can result in your application breaking. This kind of break has caused partner outages in the past.
• Use access token encryption - Your production application should use a strong encryption standard such as AES. Your production encryption key shouldn't be accessible to database administrators, business analysts, developers, or others who don't need it. The access tokens that this key protects can be used to perform any transaction on behalf of the seller and thus should be guarded like passwords.
• Show access token status - An access token status feature in your application must always show the current state of a token (valid, expired, or revoked). Sellers must always be able to revoke an access token by using the RevokeToken endpoint.
• Verify that tokens are valid - Square provides an oauth.authorization.revoked webhook event to alert partners if a token has been revoked in real time. An alternative is to periodically poll the ListLocations endpoint and check for valid and invalid responses. An invalid response indicates that a token is no longer valid.

In production, OAuth errors must be handled appropriately and errors that impact the seller must be clearly communicated to the seller. These include:

• Error codes such as UNAUTHORIZED, ACCESS_TOKEN_EXPIRED, and ACCESS_TOKEN_REVOKED must be handled. Sellers should be presented with a user-friendly message instead of API error responses.
• If your application doesn't have the required permissions, API requests can fail with an INSUFFICIENT_SCOPES error. Make sure your application has the needed permissions before moving to production.
• A common error that occurs when moving an application from the Square Sandbox to a production environment is forgetting to change the base URL. The base URL for calling Sandbox endpoints is https://connect.squareupsandbox.com. When you move your application to production, you need production credentials and you need to use https://connect.squareup.com as the base URL.

• Create the Redirect URL and Square Authorization Page URL
• Receive Seller Authorization and Manage Seller OAuth Tokens
• OAuth Walkthrough: Test Authorization with a Web Server
• OAuth Best Practices
• OAuth Permissions Reference
• Video: OAuth Best Practices
• Blog post: New Authorization Tooling – Improved Usability and Security