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.

Link to section


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.

Link to section

Migrate from renewable to refreshable token

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.


If your application calls ObtainToken with the migration_token parameter but for some reason cannot or does not store the response, it can repeat the call as long as the renewable OAuth token is still valid.

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.

Link to section

Exchange a renewable token for a refreshable token

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

  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}}" }


    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.