Migration for Redirection-based Applications

Purpose

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

You can use this API if your application either has multiple users and obtains their username and password to generate an Authtoken or makes users input their Authtokens.

Note:

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.

What do you have to do?

The application owner must share the client ID, auth token scopes, and the required OAuth scopes over an email to Zoho Mail Support. Zoho Mail will validate the details provided by you and will configure the same in Zoho Accounts. After successful validation, Zoho Mail will inform the application owner/spokesperson about the client upgrade via email.

How does it work?

  1. Once our support team successfully validate your details, you can access the below API with the Client ID, Client Secret, and Authtoken.
  2. Zoho Accounts will check if the parameters provided had been verified.
  3. After passing the check, Zoho Accounts will provide OAuth access and refresh the existing tokens.

Note:

  1. You can make a maximum migration request of up to 60 per minute and 100 per hour.
  2. After you generate the OAuth token, the already existing Authtokens will be deleted within an hour.
  3. You can pass invalid Authtoken for a maximum of 20 times. If you exceed the limit, our system will block the client and will throw the "access_denied" error message.

Request URL

https://accounts.zoho.com/oauth/v2/token/external/authtooauth

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.

Troubleshoot

Error textReason
invalid_grantThe grant_type is not specified as authtooauth.
access_denied
  • The auth token you specified is already used to generate an OAuth token. (Or)
  • You might have called the API after it has timed out. (Or)
  • The system has blocked the client.
invalid_client
  • The client ID you specified is wrong. (Or)
  • The Authtoken to OAuth entry was not made for the respective/valid client.
invalid_authtoken
  • The Authtoken you specified is wrong. (Or)
  • The Authtoken scope mismatches with the pre-shared auth scopes