Shows how to create an application that receives the seller's OAuth authorization and manages the OAuth tokens.
OAuth API

Receive Seller Authorization and Manage Seller OAuth Tokens

The next stage in the OAuth authorization process is where the seller uses the Square authorization URL you provided and logs into their Square seller account. Square shows an authorization page with the requested permissions and scope. After the seller accepts or denies the permissions, the page sends a GET to the redirect URL you specified for your application in the Developer Dashboard. This URL must match the redirect URL you specified for your application.

Requirements Permalink Get a link to this section

The application that is at the redirect URL endpoint must do the following:

  • Parse the parameters that are returned in the seller authorization response.

  • Use the authorization code in the response to call the OAuth API to obtain the seller's access and refresh tokens.

  • Manage and use the access and refresh tokens securely.

  • Encrypt the access and refresh tokens and store them securely.

  • Verify that the token used for each API call is valid.

  • Refresh the access token in a timely manner.

  • Provide the seller with the ability to revoke the access and refresh tokens.

  • Show the token status to the seller and enable them to manage authorization.

  • Ensure that API calls made with the seller's tokens can handle token-based errors appropriately.

Handle the authorization response Permalink Get a link to this section

The seller can approve or deny your authorization request. Your web page or application endpoint that receives the authorization redirect must handle the Allow or Deny responses in the query string.

If the seller chooses Allow, a production response URL 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 that this is a valid request.

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

  • code is the authorization code. Use this value when you call ObtainToken to get the access token and refresh token for the seller account. The value you provide to the ObtainToken call must match this value exactly.

If the seller chooses Deny, or if there is an error, a production response URL looks like the following: http://example.com/callback.php?error=access_denied&error_description=user_denied&state=59192b1e9f3c448569e0008b6856da50#

The 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. The access_denied value indicates that the seller denied the authorization request.

  • error_description provides more details about the error.

If the error is access_denied, you need to contact the seller to determine the reason they denied authorization. Your application should show a user-friendly page to tell the seller that authorization failed.

Call the ObtainToken endpoint Permalink Get a link to this section

If the seller authorizes your set of permissions, you must use the authorization code (code) to call the ObtainToken endpoint to get the seller's OAuth access token and refresh token. The authorization code expires 5 minutes after the Square authorization page generates the code. The value you include in the ObtainToken call must exactly match the authorization code you received. If the code expires before you get an access token, the seller must go to the Square authorization page again to create another authorization code.

An ObtainToken call looks like the following:

When you have successfully received the seller's access token and refresh token, you must store the values securely.

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

OAuth access tokens, refresh tokens, and the application secret all 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 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.

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

Ensure that 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. Your application should automatically renew OAuth access tokens every 7 days or less, regardless of whether the seller is actively interacting with your application. For more information on refreshing an access token, see OAuth Best Practices.

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

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

Square recommends that your application 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 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 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.

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

Your application must provide a mechanism for sellers to view the status of their OAuth tokens and manage the authorization for your application. Typically, this is done with a settings/configuration dashboard in your application.

Your application must accurately show the seller's access token status with Square. 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 let the seller revoke the access token. You revoke access tokens using RevokeToken. For more information about revoking an access token, see Refresh, Revoke, and Limit the Scope of OAuth Tokens.

Handle token-based errors Permalink Get a link to this section

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, and during that time the Square API returns the error ACCESS_TOKEN_EXPIRED. After that time the Square API returns an UNAUTHORIZED error. Square API calls that return the UNAUTHORIZED error are not cases of insufficient scope. Square API calls with insufficient scope return a 403 FORBIDDEN error.

Related topics Permalink Get a link to this section

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