Authorization Request

To use the Zoho Vertical Solutions APIs, the users must authenticate the application to make API calls on their behalf with an access token.

The access token, in return, must be obtained from a grant token (authorization code). The Vertical Solutions APIs use the authorization code grant type to provide access to protected resources.

Generate grant token for web-based applications

For this client type, you must use redirection-based code generation. In this authorization flow,

  • The user facilitates sign in with Vertical Solutions, from the third-party web-application.
  • The application redirects the user to the Vertical Solutions Login page, and the user enters the credentials and Submit

  • The web application redirects the user to the OAuth server with the required scope in the Accounts URL:

    {Accounts_URL}/clientoauth/v2/{PORTAL_ID}/auth?scope=ZohoCRM.settings.ALL,ZohoCRM.modules.ALL,ZohoCRM.users.ALL,ZohoCRM.org.ALL&client_id={client-id}&response_type=code&access_type={"offline" or "online"}&redirect_uri={redirect-uri}

    As you can see, the request URL has the parameters "scope", "client_id", "response_type", "access_type", and "redirect_uri".

Parameters
  • scope

    Data that your application wants to access. Refer to Scopes for more details.

  • client_id

    Client ID(consumer key) that you obtained during client registration.

  • redirect_uri

    Callback URL that you specified during client registration.

  • response_type

    Enter code.

  • access_type

    Enter access_type as online or offline. If you want to generate the refresh token, set this value as offline.

  • state

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

  • Based on the user's login details, the system automatically detects the user's domain and uses the domain-specific authentication URL to obtain the organization-specific grant token (code).
  • When the user clicks Accept: The application gets authorized. The organization-specific grant token is sent as a parameter in the redirect_uri.
  • A back-end script from your end needs to store the following details from the above URL.
    • code={grant_token} - This is used to generate access and refresh tokens.
    • location={domain} - This tells you the domain of the user from which you have to make API calls.
    • accounts-server={accounts_URL} - This is your accounts URL which you have to use to generate access and refresh tokens.
  • The application exchanges the authorization code for an access token.
  • When the user clicks Reject: The browser redirects to the redirect URI with the parameter error=access_denied, and your application is denied access to the user's data in Vertical Solutions.

Note

  • The grant token is valid only for two minutes. Refer to the Token Validity page for more details.
  • The authorization URL has the scope for Users. You can change the scope as per your requirement.
Possible Errors
  • ERROR_invalid_response_type

    Resolution: The value of the "response_type" key is not "code". Update the value as "code".
    (or)
    You have not passed the mandatory keys in the request. Pass all the mandatory keys in the request to generate the organization-specific grant token.

  • ERROR_invalid_client

    Resolution: The client ID is wrong or empty. Pass the right client ID. You can check your client ID from the console.

  • ERROR_invalid_redirect_uri

    Resolution: The redirect URI value passed, and the one registered in the console mismatches. Pass the right redirect URI.

  • ERROR_invalid_scope

    Resolution: The scope is invalid. Pass valid scopes. You can refer to the list of scopes here.