Migration for Self-Client Applications


To authenticate and generate access by refreshing the existing auth tokens to OAuth.

To perform this operation, your app should be a standalone server-side application performing a back-end job, you should not have a domain and a redirect URL.


We will be deprecating support for Zoho Authtoken from December 15, 2020. If you are still using Authtoken for authentication, we recommend you migrate to OAuth 2.0 immediately. In order to migrate to OAuth 2.0, you will need Client ID and Client secret values. Refer to the OAuth 2.0 page for further details.

How does it work?

  1. The external application will access the "Migration for Self-Client Applications" Accounts API with the client ID, client secret, auth token, and the required OAuth scopes.
  2. Zoho Accounts will validate the auth and OAuth scopes and also verify if the auth token and client ID are owned by the same user.
  3. If the validation is successful, Zoho Accounts will generate the OAuth token. After 24 hours of creating the OAuth token, Zoho Accounts will automatically delete the existing AuthToken.
  4. Once the process is complete, Zoho Accounts will send an email to the user about the client upgrade.
  5. In case the validation was unsuccessful, the system will throw the "access_denied" error.

Request URL


Request Parameters

ParameterData TypeDescription
client_id*StringThe ID that was assigned to your app when you registered it.
client_secret*StringThe unique hash generated from the connected application.
grant_type*StringThe grant_type value is "authtooauth"
authtoken*StringThe authtoken of your account.
scope*StringSpecifies the scope allowed for your app. Has to be separated by commas.
Example: ZohoMail.folders.READ, ZohoMail.folders.CREATE


Error textReason
invalid_grantThe grant_type is not specified as authtooauth.
access_deniedThe auth token you specified is already used to generate an OAuth token.
invalid_clientThe client ID you specified is wrong.
invalid_authtokenThe authtoken you specified is wrong.
invalid_scopeThe OAuth scope you specified is invalid.
invalid_requestYou have not specified valid soid parameter.


You can make a maximum migration request of up to 25 per minute and 60 per hour.

Sample Request


Sample Response

"access_token": "1000.03xxxxxxxxxxxxxxxxxa5317.dxxxxxxxxxxxxxxxxxfa",
"refresh_token": "1000.95xxxxxxxxxxxxxxxb0de.10bxxxxxxxxxxxxxxxxxx31b",
"expires_in_sec": 3600,
"token_type": "Bearer",
"expires_in": 3600000