Identity360's APIs use the industry-standard OAuth 2.0 protocol for authentication and authorization. This protocol delegates user authentication to the service hosting the user account and authorizes third-party applications to access the user account. Each API request must include an OAuth token to retrieve any resource from Identity360.
The following are some terms you need to know before you start using the Identity360 APIs.
The first step is to register your application in Zoho's API Console.
To use the Identity360 APIs, the user must authenticate the application to make API calls on their behalf with an access token. This access token, in return, must be obtained from a grant token (authorization code). The Identity360 APIs use the authorization code grant type to provide access to protected resources.
There are two ways in which you can generate the grant token based on the client type.
Web-based applications are chosen when your application is used by multiple users and require user intervention during authorization. For a web-based client, you must use redirection-based code generation. In this authorization flow, obtain an authorization grant by invoking the authorization URI, which contains the parameters listed in the table below. Refer to the example to understand how to construct this authorization URI.
Parameter | Description |
---|---|
client_ID | Client ID generated after registering the client. |
response_type | The value must be code. |
residrect_uri | Redirect URL mentioned while registering the client. |
scope | The various scopes associated with Identity360; you can use the list of scopes as per your requirements. |
access_type | Indicates offline or online; in cases where a refresh token can't be stored, use online access_type (the default will be online). |
state | An opaque value used by the client to maintain state between the request and callback. |
After you invoke the authorization URI, a user consent page opens. Once you accept it, the application gets authorized. The 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.
The application exchanges the authorization code for an access token.
If the user chooses to reject on the user consent page, 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 Identity360.
Note: The grant token is valid only for one minute.
Invoke a URL in the following format to exchange the authorization code (obtained at the end of the previous step) with an OAuth token.
Parameter | Description |
---|---|
code | Authorization code obtained after generating the grant token. |
client_id | Client ID obtained after registering the client. |
client_secret | Client secret obtained after registering the client. |
grant_type | The value must be authorization_code. |
redirect_uri | Redirect URI mentioned while registering the client. |
After invoking the URL, you will be presented with an access token, which you must include in all API calls.
Each access token is valid for only an hour and used only for the operations defined in the scope.
A refresh token does not expire. Use it to refresh access tokens when they expire.
You can only generate a maximum of five refresh tokens in a minute.
Scope name | Description | |
---|---|---|
User | idmpod.user.ALL | Grants read and write access to user and related data. |
idmpod.user.READ | Grants read access to user and related data. | |
idmpod.user.WRITE | Grants write access (create, update, and delete) to user. | |
idmpod.user.CREATE | Grants access to create a user. | |
idmpod.user.UPDATE | Grants access to update the user. | |
idmpod.user.DELETE | Grants access to delete the user. | |
Template | idmpod.template.user.READ | Grants read access to user templates and related data. |
Copyright © 2024, ZOHO Corp. All Rights Reserved.