dots
  
  
  
  
  
  

REST API Documentation:

 

The AlarmsOne API helps you achieve all the operations that can be performed on our web client. The API requires OAuth token 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.

 

 

Get OAuth token:

 

All AlarmsOne API need to be authenticated using an OAuthtoken. You can obtain an authtoken by following the below steps:

1. Registering New Client:

1. Goto this url : https://accounts.zoho.com/developerconsole
2. In the developer console enter a client name, client domain, and the redirect URL. 
 
 
3. Once you register, a Client ID and Client Secret will be generated. Take note of it for reference.
 
 

2. Generating Grant Token: 

 

Go to the following url with the below param. 

URL: https://accounts.zoho.com/oauth/v2/auth 
Params:   
  1. scope=<SCOPE for which token needs to be generated>
  2. client_id= <Client ID obtained during Client Registration>
  3. state=An opaque string that is round-tripped in the protocol; that is to say, it is returned as a URI parameter
  4. response_type=code
  5. redirect_uri=One of the redirect URI obtained in above step. This param should be same redirect url mentioned while adding Client 
  6. access_type=The allowed values are offline and online
AlarmsOne scopes:

alarmsone.alarm.READ/CREATE/UPDATE/DELETE/ALL

 

alarmsone.applications.READ/CREATE/UPDATE/DELETE/ALL

 

alarmsone.contacts.READ/CREATE/UPDATE/DELETE/ALL 

 

alarmsone.agents.READ/CREATE/UPDATE/DELETE/ALL

 

alarmsone.notificationprofile.READ/CREATE/UPDATE/DELETE/ALL

 

alarmsone.account.READ/CREATE/UPDATE/DELETE/ALL

 

alarmsone.schedules.READ/CREATE/UPDATE/DELETE/ALL

 

alarmsone.downtime.READ/CREATE/UPDATE/DELETE/ALL

 

Sample request: https://accounts.zoho.com/oauth/v2/auth?scope=alarmsone.alarm.ALL,alarmsone.applications.READ&client_id=[CLIENTID]&state=testing&response_type=code&redirect_uri=[REDIRECT URL]&access_type=offline
 
You can add multiple scopes separated by commas, as shown in the above example. [scope=alarmsone.alarm.ALL,alarmsone.applications.READ]
 
On this request, the user will be asked for permission to access the module for requested operations.
 
 

On successful authorization, Accounts will redirect to the given redirect_uri with code and state param.

 

Sample response: 
http://example.com/oauth2callback?state=testing&code=[CODE]   
This code param has to be taken from the url and to be used in the next step.

 

The code is valid only for 2 minutes, after which you should regenerate the code.

 

3. Generate Access and Refresh Token:

After getting code from the above step, make the following URL POST call.

URL : https://accounts.zoho.com/oauth/v2/token

Method : POST

Params : 

  1.  code=<Obatined in the above step.> 

  2.  client_id= <Client ID obtained during Client Registration>

  3.  client_secret=<Client secret obtained during Client Registration>

  4.  redirect_uri=<Used in the above step>

  5.  grant_type=authorization_code

Sample request : https://accounts.zoho.com/oauth/v2/token?code=[CODE]&client_id=[CLIENTID]&client_secret=[CLIENT SECRET]&redirect_uri=[REDIRECT URL]&grant_type=authorization_code

 

The access token is valid only for 1 hour. If it gets expired, run the request url again.

 

Sample response: 
{
"access_token": "1000.70d737e7cc1d8869123f796363f55345.830d0dc7ea80c404ace4a261d1b710d4",
"refresh_token": "1000.8ecd474019e31d52d2f94aad659c5cb7.4638677ebc14f2f2ee410b6dfb6cebdc",
"token_type": "Bearer",
"expires_in": 3600000
}

 

  • In this response, you will get both access_token and refresh_token. 

  • The access_token will expire after a particular period of time (as given in expires_in param). 

  • The refresh_token is permanent and can be used to regenerate new access_token, if the current access token expires.

 

4. Generate Access Token From Refresh Token

URL : https://accounts.zoho.com/oauth/v2/token

Method : POST

Params :  

  1. refresh_token =<Obtained in the above step.> 

  2.  client_id= <Client ID obtained during Client Registration>

  3.  client_secret= <Client secret obtained during Client Registration>

  4.  redirect_uri=<Used in the above step>

  5. grant_type= refresh_token 

 

5. Revoking an Refresh Token : 

 

URL : https://accounts.zoho.com/oauth/v2/token/revoke. 

Method : POST

Params : token = <Refresh token>

 

6. Calling An API : 

  • Access Token can be passed only in header. It can not be passed as param.

  • Header name should be Authorization

  • Header value should be Zoho-oauthtoken<space><access token>

 

 

API index:

 

1. Alarms

2. Applications

3. Contacts

4. Notification Profiles

5. Agents

6. Schedules and Overrides

7. Downtime

8. Account

9. Error codes and Messages