Generate Access Token and Refresh Token

OAuth2.0 requests are usually authenticated with an access token, which is passed as bearer token. To use this access token, you need to construct a normal HTTP request and include it in an Authorization header along with the value of Bearer.

Note

  • You must use your domain-specific Zoho Accounts URL to generate access and refresh tokens. The following are the various domains and their corresponding accounts URLs.
    • For US: https://{Your_Solution_Name}.zohoplatform.com
    • For EU: https://{Your_Solution_Name}.zohoplatform.eu

To generate access and refresh token:

  1. Make a POST request with the following URL. Replace {Accounts_URL} with your domain-specific Zoho accounts URL when you make the request.

    {{Accounts_URL}}/clientoauth/v2/{PORTAL_ID}/token

    Note: For security reasons, pass the below parameters in the body of your request as form-data.

    Request Parameters

    • grant_type

      Enter the value as "authorization_code".

    • state

      An opaque string that is round-tripped in the protocol; i.e, it is returned as a URI parameter.

    • client_id

      Specify client-id obtained from the connected app.

    • client_secret

      Specify client-secret obtained from the connected app.

    • redirect_uri

      Specify the Callback URL that you registered during the app registration.

    • code

      Enter the grant token generated from previous step.

  2. If the request is successful, you would receive the following:

    {
            "access_token": " ***** ",
            "scope": "ZohoCRM.settings.ALL ZohoCRM.modules.ALL ZohoCRM.users.ALL ZohoCRM.org.ALL",
            "api_domain": "https://www.zohoapis.com",
            "token_type": "Bearer",
            "expires_in": 3600
            }

    Response Parameters

    • access_token

      Access token to access Vertical Solutions APIs.

    • refresh_token

      Refresh token to obtain new access tokens.

    • expires_in

      Time in seconds after which the access token expires.

    • api_domain

      Domain name of the API. Use this domain in your requests to make API calls to your Vertical Solution.

    • token_type

      Type of token obtained. "Bearer" indicates this is an access token.

This completes the authentication. Once your app receives the access token, send the token in your HTTP authorization header to Vertical Solutions API with the value "Zoho-oauthtoken {access_token}" for each endpoint (for each request).

Note

  • Each access token is valid for only an hour and can be used only for the operations defined in the scope.
  • A refresh token does not expire. Use it to refresh access tokens when they expire. For more details on the validity of the tokens, refer to Token Validity page.
  • Use the value in the "api_domain" key to make API calls to Vertical Solutions. The URL varies based on the environment.

Possible Errors

  • invalid_client

    Resolution: You have passed an invalid Client ID or secret. Specify the correct client ID and secret.
    (or)
    There is a domain mismatch. You have registered the client and generated the grant token in a certain domain (US), but generating the tokens from a different domain (EU). Ensure that you generate the grant, access, and refresh tokens from the same domain using the same domain URL.

  • invalid_code

    Resolution: The grant token has expired. The grant token is valid only for one minute in the redirection-based flow. Generate the access and refresh tokens before the grant token expires.
    (or)
    You have already used the grant token. You can use the grant token only once.
    (or)
    The refresh token to generate a new access token is wrong or revoked. Specify the correct refresh token value while refreshing an access token.

  • invalid_redirect_uri

    Resolution: The redirect URI in the request mismatches the one registered in the console. Specify the correct redirect URI in the request.