A list of tasks for a developer to take to move an application from using the Square Sandbox to a production environment.
OAuth API

Move OAuth from the Sandbox to Production

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 API Best Practices before moving an application to production.

If your application relies on a pubic client, regardless of whether it is a mobile application, single-page web application, or relies on a web browser, you should use PKCE flow. Public clients can be decompiled and credentials such as the client_secret can be easily obtained, and the PKCE flow process does not rely on the client_secret being stored on the client. For more information on PKCE flow, see OAuth Overview.

Important

Partner developers must not request nor use personal access tokens from the Square sellers who use their applications. Personal access tokens never expire and they have all permissions associated with the account owner. OAuth access tokens should be used instead to access seller resources.

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 are not 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 is not 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 does not 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 are 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 is 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 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 that the state value matches your generated CSRF token.

  • 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:

  • Do not 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.

  • Required 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 on retrieval 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 is a problem with your renewal login. Avoid silent token failures, which result in your application breaking. This kind of break has caused partner outages in the past.

  • Access token encryption. Your production application should use a strong encryption standard such as AES. Your production encryption key should not be accessible to database administrators, business analysts, developers, or others who do not 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 does not 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.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.