Get authorization code

Request for an authorization code from our authorization server. You will need to mention which scopes you need permission for. We will display the requested permissions to the administrator. If they are the administrator of multiple instances, they will have to select which instance to grant permission for. If they grant it, an authorization code will be sent to your redirect URL, which is valid for 2 minutes.

Endpoint

CopiedGET 	{accounts-server-url}/oauth/v2/org/auth

 Note: The accounts-server-url is specific to the location (i.e., datacenter) where your app is registered.  

Query parameters

ParameterDescription
client_id

required

The unique ID of your application. You can find this in the API console.

response_type

required

Should be sent with the value code.

redirect_uri

required  

The URI to which the authorization server will redirect the browser back with the authorization code. It has to be the same URI which is provided when registering the app in the API console. Should start with http:// or https://. 

 

For example: https://www.zylker.com/oauthredirect

scope

required  

The corresponding scope for the resource you want to access from the user's account. The scopes will be displayed to the administrator when asking for consent.

 

Eg: ZohoCRMsettings.READ

 

Refer to points to note for allowed scopes

access_type

optional  

Determines whether your app can refresh the access token on its own once the access token expires (without user intervention). If the value is online, only the access token will be provided and it cannot be refreshed by the app once expired. If the value is offline, a refresh token will also be provided for the first time the app requests for an access token, which the app can store and then use to refresh the access token whenever required.

 

Default value: online

 

Note: To get a refresh token every time the app requests for an access token, then include access_type=offline and prompt=consent when making the authorization request.  

Request example

Copiedhttps://accounts.zoho.com/oauth/v2/org/auth
?response_type=code
&client_id=1000.GMB0YULZHJK411284S8I5GZ4CHUEX0
&scope=ZohoCRM.Modules.Read
&redirect_uri=https://www.zylker.com/oauthredirect
&access_type=offline

Response parameters

ParameterDescription
codeThe authorization code that can be exchanged for an access token. Its validity is two minutes and can be used only once.
location

Indicates the data center (DC) location of the app instance. If its DC is different from that of your app, then you will need to enable multi DC support and make the access token request to the app instance's DC.

Response example

Copiedhttps://www.zylker.com/oauthredirect
?code=1000.a1110799eac53c491fee9efef8246535.df7da86ff64daa66413e2899e9b7fad7
&location=in
&accounts-server=https://accounts.zoho.in

Error codes

ParameterDescription
access_denied
  • Administrator rejected the request for access.
  • Reached throttle limit. Refer to OAuth token limits.
Invalid Client

  • The value of the parameter "client_id" is not valid.

  • The value of the parameter "response_type" is incorrect. It must be "code".

  • The client is not an "ORG" type client.

Invalid Response Type

  • The parameter "client_id" is missing.

  • The parameter "response_type" is missing.

Invalid OAuth Scope

  • The parameter "scope" is either missing or the entered scope doesn't exist.

  • Scopes of more than one Zoho app are included in the request (excluding allowed services). Refer to points to note section.

Scope Changes Required
  • A scope of a business Zoho app is not included in request. At least one scope must be requested (other than that of the common services). Refer to points to note section.
Invalid Redirect Uri
  • The parameter "redirect_uri" is either missing or the entered URI doesn't match with the one configured in the API console.
An error occurred/500 server error

  • The value of the parameter "response_type" is invalid. It must be "code".

  • Scopes are not separated properly. Check if they are correctly separated by only commas and with no spaces.

404 not found

  • The HTTP method used is incorrect. It must be GET.