Learn how to migrate your Square API authentication logic to use OAuth refresh tokens.
Docs Home
Dev Essentials
Payments Commerce Customers Staff Merchants
Partnerships
Release notes

Docs

Docs Home
Dev Essentials
Payments
Commerce
Customers
Staff
Merchants
Partnerships
Release notes
Docs
OAuth API

Migrate from Renew to Refresh OAuth 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 will be retired on 2024-04-13.

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.

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
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    curl https://connect.squareupsandbox.com/oauth2/token \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -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}}"
  }'
    Try in API Explorer

  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.

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    {
  "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.

On this page
We've made improvements to our docs.
Prefer the old format?