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.
If your application caches and uses the deprecated renewable token, do the following steps to migrate to refreshable tokens:
Call the
ObtainToken
endpoint with thegrant_type
parameter ofmigration_token
, passing the old renewable token.Get the new OAuth token from the response.
Get the refresh token from that same response.
Cache both of tokens from the response securely.
Use the refreshable OAuth token flow with the following steps:
Use the new OAuth token in all Square API rest calls.
Before the OAuth token expires, refresh it by using the
refresh_token
grant type in theObtainToken
endpoint to get a new OAuth token.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:
In the Developer Dashboard, make sure your application is using Square API version 2019-03-13 or later.
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 tomigration_token
.Set the
migration_token
parameter to the non-expired renewable OAuth access token to migrate.
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.
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.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.