Migrate to Using Refresh Tokens

When updating to Square API v2019-03-13 or newer, you need to update OAuth access tokens created with an older Square API version before they expire.

OAuth access tokens created using a Square API version prior to 2019-03-13 will continue to work. However, RenewToken is deprecated in version 2019-03-13.

When you update to a newer API version, it is important that you update your existing OAuth access tokens before they expire, using the the following migration process:

  1. In the Square Developer Portal make sure your application is on Connect API version 2019-03-13 or later.

  2. Send 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 legacy OAuth access token to migrate

  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.


The new access token will expire 30 days from time of creation. After it expires you use the refresh token to generate a new access token by sending request to the ObtainToken endpoint. For an example, see Obtain a New OAuth token Using a Refresh Token

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 will provide a replacement access token and refresh token.