Migrate from Renew to Refresh OAuth Tokens

Applies to: OAuth API

Learn how to use the OAuth API to migrate your Square API authentication logic to use OAuth refresh tokens.

When updating your application to use Square API version 2019-03-13 or newer, your code must use the OAuth refresh token flow instead of the deprecated renew token flow. Renewable OAuth access tokens created with older versions of the Square API must be replaced by refreshable tokens before the older tokens expire.

OAuth access tokens created using a Square API version prior to 2019-03-13 continue to work until they expire. However, RenewToken is deprecated in Square API version 2019-03-13. RenewToken is retired on 2024-04-17. If you haven't migrated your application to use refreshable tokens before that date, users will not be able to authorize your application to access their Square accounts.

If your application caches and uses the deprecated renewable token, do the following steps to migrate to refreshable tokens:

1. Call the ObtainToken endpoint with the grant_type parameter of migration_token, passing the old renewable token.
2. Get the new OAuth token from the response.
3. Get the refresh token from that same response.
4. Cache both of tokens from the response securely.

Use the refreshable OAuth token flow with the following steps:

1. Use the new OAuth token in all Square API rest calls.
2. Before the OAuth token expires, refresh it by using the refresh_token grant type in the ObtainToken endpoint to get a new OAuth token.
3. If token expires without being refreshed, use the authorization_code grant type to restart the authentication flow.

For more information about the new OAuth flow, see OAuth API Overview.

Use the following migration process to replace a renewable token with a refreshable token:

1. In the Developer Dashboard, make sure your application is using Square API version 2019-03-13 or later.

2. POST a request to the ObtainToken endpoint. In the request body, specify the non-expired legacy access token as follows:

   • Set the grant_type parameter to migration_token.
   • Set the migration_token parameter to the non-expired renewable OAuth access token to migrate.

   Obtain token

   cURL

3. In the response, Square returns a new access token along with a refresh token. You should persist both the access token and refresh token and use these credentials going forward.

   {
     "access_token": "{{REFRESHABLE_ACCESS_TOKEN}}",
     "token_type": "bearer",
     "expires_at": "2020-11-26T21:15:07Z",
     "merchant_id": "{{MERCHANT_ID}}",
     "refresh_token": "{{REFRESH_TOKEN}}"
   }

   Important

   The new access token expires 30 days after it's created. After it expires, you use the refresh token to generate a new access token by sending a request to the ObtainToken endpoint.

If any of the preceding steps fail, you can safely repeat the process with the legacy access token you're trying to migrate. As long as the legacy token isn't expired, this process provides a replacement access token and refresh token.