Learn how to refresh, revoke, and limit the scope of OAuth tokens.
OAuth API

Refresh, Revoke, and Limit the Scope of OAuth Tokens

When you have the access and refresh tokens for a seller, you must be able to refresh the access token, revoke the tokens, and limit the scope of the tokens if required.

Your application must also provide a mechanism for sellers to view and manage 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 status of the seller's OAuth access token with Square. The status of the OAuth access token must always be accurate and indicate the correct state of the access token (valid, expired, or revoked). Your application can check the validity of the token by calling ListLocations and checking the response.

Refresh the access token Permalink Get a link to this section

Your application should be able to refresh the access token before it expires in 30 days. 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 access 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. For more best practice ideas, see OAuth API Best Practices.

To refresh an access token, you call the ObtainToken with the following information:

  • client_id. Your application's production application ID.

  • client_secret. Your application's production application secret.

  • grant_typerefresh_token.

  • refresh_token. The refresh token for the seller.

A call to ObtainToken to refresh an access token looks similar to the following:

A successful call to ObtainToken using the refresh token returns a 200 response code and includes information about the new access token. Use this new access token for calling the Square APIs on the seller's behalf. A successful call looks similar to the following:

Revoke the access token Permalink Get a link to this section

Your application should give the seller the ability to manage their OAuth tokens, including the ability to revoke the OAuth tokens if they choose to. Revoking the OAuth tokens stops your ability to manage resources on behalf of the seller. Your application can call the RevokeToken endpoint to revoke the seller token.

To revoke an access token, you call the RevokeToken with the following information:

  • client_secret. Your application's production application secret.

  • access_token. The seller's access token that you want to revoke. You can specify the access token or the merchant_id; you do not need to specify both.

  • client_id. Your application's production application ID.

  • grant_typerefresh_token.

  • refresh_token. The seller's refresh token.

A call to RevokeToken to revoke an access token looks similar to the following:

A successful call to RevokeToken returns a 200 response code and looks similar to the following:

Revoke authorization for a single OAuth access token Permalink Get a link to this section

The default behavior for the Square RevokeToken endpoint revokes the entire authorization for you to act on the behalf of a seller. However, you might need to revoke a specific access token without terminating the entire seller authorization. For example, if an access token is compromised, you want to revoke the compromised token and generate a new one without requiring a new seller authorization.

The revoke_only_access_token is an optional field in the RevokeToken endpoint. This field lets you revoke a specified OAuth access token without terminating the entire authorization.

A call to RevokeToken to revoke a single access token, but not terminate authorization, looks similar to the following:

A successful call to RevokeToken returns a 200 response code and looks similar to the following:

Modify the scope and duration of OAuth access tokens Permalink Get a link to this section

The default expiration for OAuth access tokens was 30 days because credentials were traditionally used from a tightly controlled access environment such as a secure server. As developers expand their use cases to include loosely controlled access environments such as web browsers or mobile clients, there is a need for credentials with limited permissions and a shorter lifespan to prevent errors and mitigate risk.

Create limited scope OAuth access tokens Permalink Get a link to this section

If you do not need all the permissions granted by an access token, you can create a new access token that has a reduced set of permissions from the ones granted when the seller approved your authorization. You do this by creating a new access token for the seller using the optional scopes field on the ObtainToken endpoint.

For example, if a seller granted four permissions including MERCHANT_PROFILE_READ, PAYMENTS_READ, PAYMENTS_WRITE, and BANK_ACCOUNTS_READ and you find that you only need two, MERCHANT_PROFILE_READ and PAYMENTS_READ, then you can create a new access token with just those two permissions.

A call to ObtainToken to limit the scope of an access token looks similar to the following:

The API response does not include a list of scopes. If a 200 response is returned, it can be assumed that the scopes have been added to the newly created OAuth access token. A successful call to ObtainToken returns a 200 response code and looks similar to the following:

Important

The newly created OAuth access token cannot be viewed in the Developer Dashboard. Your application must store this new token for future use.

Create short-lived OAuth access tokens Permalink Get a link to this section

The default expiration for OAuth access tokens is 30 days. A 30-day lifespan is not appropriate for use in less secure web or mobile clients. The 30-day expiration increases the risk duration for exposure and abuse. When working within loosely controlled access environments such as web browsers or mobile clients, you might prefer a credential with a shorter lifespan to prevent errors and mitigate risk.

The short_lived optional field within the ObtainToken endpoint lets you generate a short-lived access token that expires 24 hours after creation.

To create an access token that expires in 24 hours, call ObtainToken and set the short_lived field to true. The call looks similar to the following:

A successful call to ObtainToken returns a 200 response code and looks similar to the following:

Note

The lifespan of the short-lived access token cannot be customized. It always has a 24-hour lifespan.

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.