Explain this to me:

Introduction
API Root Endpoint

United States
https://www.site24x7.com/api
Europe
https://www.site24x7.eu/api
China
https://www.site24x7.cn/api
India
https://www.site24x7.in/api
Australia
https://www.site24x7.net.au/api
Japan
https://app.site24x7.jp/api
The Site24x7 API helps you achieve all the operations that can be performed on our web client.

The API requires OAuthtoken as an account identifier. This API is built using the REST principles which ensures predictable URLs that make writing applications easy. This API follows HTTP rules, where a wide range of HTTP clients can be used to interact with the API.

Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API Root Endpoint.

We have multiple data centers in Site24x7:

United States - .com
Europe - .eu
China - .cn
India - .in
Australia - .net.au
All examples in the document, except Japan, are based on COM domain. You can change the DC Root endpoint of any example from COM to any DC you want to access.

For Japan DC, the API Root Endpoint would be https://app.site24x7.jp

Getting Started
Example

$ curl https://www.site24x7.com/api/monitors \
    -H 'Accept: application/json; version=2.0' \ 
    -H 'Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7ab2d1.8fcc9810810a216793f385b9dd6e125f' \ 
All Site24x7 APIs require a Authorization request header for authentication.


Authentication
Zoho Accounts Root Endpoint

United States
https://accounts.zoho.com
Europe
https://accounts.zoho.eu
China
https://accounts.zoho.com.cn
India
https://accounts.zoho.in
Australia
https://accounts.zoho.com.au
Japan
https://accounts.zoho.jp
Site24x7 REST APIs uses the OAuth 2.0 protocol to authorize and authenticate calls. The OAuth protocol provides a more secure access to protect resources, thereby reducing the hassle of asking for a username and password every time a user logs in.

We have multiple data centers in Zoho:

United States - .com
Europe - .eu
China - .com.cn
India - .in
Australia - .com.au
Japan - .jp
All examples in PART 1 - 4 are based on COM domain. You can change the DC Root endpoint of any example from COM to any DC you want to access.

Please follow the steps below to access Site24x7’s APIs using OAuth 2.0:

PART 1: REGISTERING NEW CLIENT APPLICATION
Register your application with Site24x7 to get your Client ID and Client Secret. For script-based API calls, the Self Client option in the Zoho Developer Console is preferrable or check out the other options based on your client types.

To register your application using the Self Client option,

Go to Zoho Developer Console and click on Get Started Now > Self Client > Create Now.
United States
Europe
China
India
Australia
Japan
Click on Create. Confirm the process. On successful registration, you will be provided with a set of OAuth 2.0 credentials such as Client ID and Client Secret, that are known to both Zoho and your application.
Note: Do not share these credentials to anyone.

PART 2: GENERATING GRANT TOKEN
Once you have successfully registered the client application, generate a grant token to obtain authorization to use the APIs based on your requirement.

If you have generated the OAuth 2.0 credentials using the Self Client option, then please follow the steps below:

Go to Zoho Developer Console and click on the created Self Client.

Navigate to the Generate Code tab and provide the Scope List of scopes (based on the API calls that you are going to use), Description, and the Time Duration for its validity (from 3 minutes to 10 minutes). Get the scopes for the APIs from their respective API document and separate multiple scopes with commas.

Click Generate. Copy the code for the mentioned scope.

For other client types (such as web-based), refer here.

Note: Generating a Grant Token is a one-time process. It cannot be generated via API call. Once the Grant Token is generated, refer Part 3 to create a Refresh Token immediately before the former expires. Please note that the Refresh Token is permanent and has no expiry.

PART 3: GENERATE ACCESS AND REFRESH TOKEN
POST https://accounts.zoho.com/oauth/v2/token?client_id={client_id}&client_secret={client_secret}&code={code}&grant_type=authorization_code
After getting the grant token from the above step, make a POST request for the following URL with the given params to generate the access_token:

Request Example

$ curl  https://accounts.zoho.com/oauth/v2/token \
        -X POST \
        -d "client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V" \
        -d "client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf"\
        -d "code=1000.dd7e47321d48b8a7e312e3d6eb1a9bb8.b6c07ac766ec11da98bf6a261e24dca4"\
        -d "grant_type=authorization_code" \



Response Example

{
    "access_token":"1000.2deaf8d0c268e3c85daa2a013a843b10.703adef2bb337b 8ca36cfc5d7b83cf24",
    "refresh_token":"1000.18e983526f0ca8575ea9c53b0cd5bb58.1bd83a6f2e22c3a7e1309d96ae439cc1",
    "expires_in":3600,
    "api_domain":"https://www.zohoapis.com",
    "token_type":"Bearer"
}
Parameter	Description
client_id	Mandatory
Client ID obtained during Client Registration.
client_secret	Mandatory
Client Secret obtained during Client Registration.
code	Mandatory
The grant token that is obtained in the above step.
grant_type	Mandatory
Value must be authorization_code
In the response, you will get both access_token and refresh_token.

The access_token will expire after some specified seconds (represented by expires_in param in the response). You can regenerate a new access_token using the refresh_token (Refer Part 5: Generate Access Token from Refresh Token).
The refresh_token is permanent. To revoke a refresh_token, refer Part 6: Revoking a Refresh Token.
Note:

Each time a re-consent page is accepted, a new refresh token is generated.
The maximum limit is 20 refresh tokens per user. If this limit is crossed, the first refresh token is automatically deleted to accommodate the latest one. This is done irrespective of whether the first refresh token is in use or not.
You can generate a maximum of 20 refresh tokens in a span of 10 minutes per client ID.
Each refresh token can have a maximum of 10 active access tokens (non expired). When the user creates the 11th access token, the first created access token is automatically deleted to accommodate the latest one.
You can also refer to sample scripts in the community post. Read the kbase article to know about the common OAuth Errors.

PART 4: CALLING AN API
Once the access and the refresh tokens are generated, API calls can be made by passing the access token in the header.

Header name should be Authorization
Header value should be Zoho-oauthtoken {access_token}
To access an MSP Customer or a BU’s data you need to pass their ZAAID in the header. For more information.

Header name should be Cookie
Header value should be zaaid={zaaid of the customer/bu}
Note: Access tokens cannot be passed in the request param.

Example

$ curl https://www.site24x7.com/api/monitors \
    -H 'Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7ab2d1.8fcc9810810a216793f385b9dd6e125f' \ 
List of scopes available in Site24x7:

Scope	Description
account	To access, add, edit, delete users and license related data.
Availabe types: Site24x7.Account.Read, Site24x7.Account.Create, Site24x7.Account.Update, Site24x7.Account.Delete, Site24x7.Account.All
admin	To access, add, edit, delete monitors, configuration profiles, third party integrations etc.
Availabe types: Site24x7.Admin.Read, Site24x7.Admin.Create, Site24x7.Admin.Update, Site24x7.Admin.Delete, Site24x7.Admin.All
reports	To access, add, edit, delete reports and monitor status.
Availabe types: Site24x7.Reports.Read, Site24x7.Reports.Create, Site24x7.Reports.Update, Site24x7.Reports.Delete, Site24x7.Reports.All
operations	To access, add, edit, delete operation related data such as IT Automation, maintenance, status page announcements etc.
Availabe types: Site24x7.Operations.Read, Site24x7.Operations.Create, Site24x7.Operations.Update, Site24x7.Operations.Delete, Site24x7.Operations.All
msp	To access, add, edit, delete MSP related data.
Availabe types: Site24x7.Msp.Read, Site24x7.Msp.Create, Site24x7.Msp.Update, Site24x7.Msp.Delete, Site24x7.Msp.All
bu	To access, add, edit, delete Business Units related data.
Availabe types: Site24x7.Bu.Read, Site24x7.Bu.Create, Site24x7.Bu.Update, Site24x7.Bu.Delete, Site24x7.Bu.All
PART 5: GENERATE ACCESS TOKEN FROM REFRESH TOKEN
POST https://accounts.zoho.com/oauth/v2/token?client_id={client_id}&client_secret={client_secret}&refresh_token={refresh_token}&grant_type=refresh_token
Access tokens have limited validity. In most of the cases, the access tokens expire in one hour. Until then, the access token has unlimited usage. Once it expires, your app will have to use the refresh token to request for a new access token.

Note:

You can generate a maximum of 10 access tokens in a span of 10 minutes.
Make the following POST request with the given params to get a new access token:

Request Example

$ curl https://accounts.zoho.com/oauth/v2/token \
        -X POST \
        -d "client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V" \
        -d "client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf" \
        -d "refresh_token=1000.8ecd474019e31d52d2f94aad6c5cb7.4638677ebc14f2f2ee0b6dfb6cebdc"\
        -d "grant_type=refresh_token" \
Response Example

{
    "access_token":"1000.2deaf8d0c268e3c85daa2a013a843b10.703adef2bb337b 8ca36cfc5d7b83cf24",
    "expires_in":3600,
    "api_domain":"https://www.zohoapis.com",
    "token_type":"Bearer"
}
Parameter	Description
client_id	Mandatory
Client ID obtained during Client Registration.
client_secret	Mandatory
Client Secret obtained during Client Registration.
refresh_token	Mandatory
REFRESH TOKEN using which a new access token has to be generated.
grant_type	Mandatory
Value must be refresh_token.