Migrate from Renew to Refresh OAuth Tokens

When updating your application to use Square API 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 version Square API version 2019-03-13.

Migrate from renewable to refreshable token Permalink Get a link to this section

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 re-start the authentication flow.

For more information about the new OAuth flow, see How OAuth Works.

Exchange a renewable token for a refreshable token Permalink Get a link to this section

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

  1. In the Square 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
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    curl https://connect.squareupsandbox.com/oauth2/token \
      -X POST \
      -H 'Square-Version: 2021-09-15' \
      -H 'Content-Type: application/json' \
      -d '{
        "client_id": "{{CLIENT_ID}}",
        "client_secret": "{{CLIENT_SECRET}}",
        "grant_type": "migration_token",
        "migration_token": "{{RENEWABLE_OAUTH_TOKEN}}",
        "redirect_uri": "https://{{YOUR_REDIRECT_URL}}"
  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 is 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 are trying to migrate. As long as the legacy token is not expired, this process provides a replacement access token and refresh token.