Step 1: Create authorization request
To obtain user authorization for accessing API endpoints, you must construct an authorization request link and provide a way for users to access the request link.
The authorization request link looks like the following:
https://accounts.zoho.com/oauth/v2/auth?scope={scopes}&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}
The authorization request link has the following components:
- Accounts URL - the API domain of Bigin authorization server that authenticates a user and then prompts the user to accept or reject your client's API access request. For example, https://accounts.zoho.com/v2/oauth.
Note: When you create an authorization request, use https://account.zoho.com for accounts hosted in US, EU, AU, and IN domains and https://accounts.zoho.com.cn for accounts hosted in CN. For more information, see Multi DC Support.
- Query parameters - Along with the account URL, you must include query parameters that provide the context of a request to the authorization server.
The query parameters include the following:
| Parameter | Description | Example |
|---|---|---|
| response_typerequired | Indicates the type of response. This parameter informs the Bigin authorization server about the type of response the client is requesting. In this case, as the Bigin uses authorization code grant type and the client requests for authorization code, set the response_type value to code. | response_type = code |
| client_idrequired | Indicates the client identifier of your web application. This parameter helps the Bigin authorization server to identify a client who is requesting user authorization. For more information about client identifier, see Register your application. | client_id = 1000.690CGFL9IO0QAAXY7904YOBT4IHLGY |
| scoperequired | Indicates the scope of the access request. This parameter informs the Bigin authorization server about the level of access the client is requesting. You can set the single scope or multiple scopes separated by a comma as shown in the example section. For more information, see Scopes. | scope = ZohoBigin.modules.ALL (or) scope = ZohoBigin.settings.modules.READ,ZohoBigin.settings.modules.WRITE,ZohoBigin.settings.DELETE |
| redirect_urirequired | Indicates the URI of the page to which the Bigin authorization server sends back the response once the user grants access. The value of this parameter must be the same as the Authorized Redirect URIs value, which is specified while registering your client. | redirect_uri = https://www.yourdomain.com/callback |
| access_typerecommended | Indicates the type of access. The value for this parameter can be any of the following:
| access_type = online (or) access_type = offline |
A sample authorization request with required and recommended query parameters is provided in the following:
https://accounts.zoho.com/oauth/v2/auth?response_type=code&client_id=1000.690CGFL9IO0QAAXY7904YOBT4IHLGY&scope=ZohoBigin.settings.modules.READ,ZohoBigin.settings.modules.WRITE,ZohoBigin.settings.DELETE&access_type=offline&redirect_uri=https://www.yourdomain.com/callback
The above sample request has access_type as offline so it can be used to generate both access and refresh tokens.