LogicMonitor REST API version 3 (also referred as API v3) is the actively supported version. While API v1 and v2 remain functional, they no longer receive updates. To take advantage of the latest features, enhancements, and security improvements, LogicMonitor recommends migrating to API v3.

Reasons to migrate to LogicMonitor REST API v3:

• API v3 is an upgraded version of API v2 and has all the latest features
• Enhancements and defect fixes are done only to API v3
• API v3 has in depth product documentation

It is essential to understand the impact of migration to API v3 on your existing integrations. In API v3, there are significant improvements to authentication methods, response formats, and error handling that can impact your custom scripts and applications. You must understand these changes to ensure smooth transition and prevent potential disruption of your workflows.

LogicMonitor provides the following product documentation for your migration:

• For more information on the prerequisites for a successful migration including key migration considerations, see General Requirements for Migration to LogicMonitor REST API v3.
• For more information on the specific changes when migrating from API v2 to API v3 including header updates and filter syntax adjustments, see Migration from LogicMonitor REST API v2 to API v3.
• For more information on the significant advancements and differences between API v1 and API v3, including URL structure, authentication changes, and new HTTP method, see Migration from LogicMonitor REST API v1 to API v3.

If you have any questions or require assistance during the migration process, contact the Support team.

For more information, see the following:

• Using LogicMonitor’s REST API
• LogicMonitor REST API v3 Swagger Documentation
• LogicMonitor v3 SDKs
• Best Practices for Migrating to LogicMonitor v3 SDK
• LogicMonitor REST API v3 Basic filters
• LogicMonitor REST API v3 Advanced filters
• Bearer Token

To migrate to LogicMonitor REST API v3, you need the following:

• A valid LMv1 API token or bearer token for authentication.
• Access to Swagger documentation from LogicMonitor for API v3 reference.

LogicMonitor REST API v3 Migration Considerations

• Update authentication method—Replace basic authentication with token-based authentication such as, LMv1 or bearer token. For more information, see REST API Authentication.
• Update API request headers—Use the new version 3 header (X-version: 3) or query parameter (v=3) in the API calls.
• Modify API URLs—Update endpoints to match the new v3 structure. For more information, see the API URL mapping table.
• Adapt to new response formats—Modify the client code to handle the new response format.
• Update error handling—Update the error handling logic to accommodate the new error response format.
• Update API filters—Update API filters according to the changes specified in the Filter Syntax section. For more information, see LogicMonitor REST API v3 Basic filters and LogicMonitor REST API v3 Advanced filters.
• Update parsing logic—Remove any logic that parses the status, errmsg, and data fields.
• Access fields from root—Access fields directly from the root of the JSON response.
• Simplify fields—Ensure that the client can correctly interpret the errorMessage, errorCode, and errorDetail fields.
• Test your scripts or applications—Use sample code and API v3 Swagger to validate your updates. For more information, see REST API v3 Swagger Documentation.

LogicMonitor REST API v3 has all the enhancements and fixes compared to API v2. The following are key highlights why you must migrate to API v3:

• API v3 version header updates
• Support for filter syntax

LogicMonitor REST API v2 to v3 Changes

Version Header for REST API v2 to API v3

You can make API v3 request using one of the following version headers:

• Header X-version with value 3. For example, “X-version: 3”
• API query parameter v with value 3. For example, “v=3”

For more information, see REST API v3 Swagger Documentation.

API Response Format for REST API v2 and API v3

There is no difference in the success and error response format of API v2 and API v3. Therefore, migrating from API v2 to API v3 does not require any changes to the parsing logic.

Success Response for REST API v2 and v3

The success response format for API v3 is as follows:

{
   <API specific data>
}

Error Response for REST API v2 and API v3

The error response format for API v3 is as follows:

{
    "errorMessage": <ERROR_MESSAGE>,
    "errorCode": <ERROR_CODE>,
    "errorDetail": null
}

Example of Response Format in Python Code

import json
  
# Success Response Handling
def handle_success_response(json_response):
    response = json.loads(json_response)
    # Process the fields directly from the response
    # Example: total = response['total']
  
# Error Response Handling
def handle_error_response(json_response):
    response = json.loads(json_response)
    error_message = response['errorMessage']
    error_code = response['errorCode']
    error_detail = response['errorDetail']
    # Process the error message, code, and detail

LogicMonitor REST API v3 is far more advance than API v1. All enhancements and fixes are done only to API v3. The following are key highlights why you must migrate to API v3:

• API v3 version header updates
• Support for token-based authentication
• Support for filter syntax
• Support for the PATCH method
• API URL updates 

Requirements for Migration from LogicMonitor REST API v1 to API v3

To migrate to API v3, you need the following:

• A valid LMv1 API token or bearer token for authentication.
• Access to Swagger documentation from LogicMonitor for API v3 reference.

LogicMonitor REST API v1 to API v3 Changes

You must note the following changes in both the API v1 and API v3:

• Authentication updates
• Support for PATCH method to partially update an endpoint
• Updates to the version header
• Updates to success and error response format

Support for Token-based Authentication

Starting with API v2, LogicMonitor no longer supports basic authentication. It is done to encourage use of API tokens for authentication. The API tokens are secure, they help in separation of LogicMonitor portal and LogicMonitor REST API access, and audit log entries.

To encourage use of taken-based authentication, LogicMonitor supports LMv1 API and bearer token for API v2 and API v3. For more information, see REST API Authentication.

Support for PATCH Method

API v3 includes support for PATCH method for most of the API endpoints. You may find this useful for updating specific fields of an endpoint, instead of using the PUT method for updating all the fields (that is, the entire API endpoint). For more information, see REST API v3 Swagger Documentation.

Version Header for REST API v1 to API v3

You can make API v3 request using one of the following version headers:

• Header X-version with value 3. For example, “X-version: 3”
• API query parameter v with value 3. For example, “v=3”

For more information, see REST API v3 Swagger Documentation.

Adding Version Header using cURL

Enter the following command and use -H or --header followed by the header name and value:

curl -H "X-version: 3" https://COMPANY.logicmonitor.com/santaba/rest/device/devices/1

curl --header "X-version: 3" https://COMPANY.logicmonitor.com/santaba/rest/device/devices/1

curl "https://COMPANY.logicmonitor.com/santaba/rest/device/devices/1?v=3"

Adding Version Header using Python

Enter the following command and use the headers parameter in the requests library.

headers = {'X-Version':'3'}
response = requests.get("https://COMPANY.logicmonitor.com/santaba/rest/device/devices/1", headers=headers)

response = requests.get("https://COMPANY.logicmonitor.com/santaba/rest/device/devices/1?v=3")

API Response Format for REST API v1 to API v3

The following are the key updates to API response format:

• Removal of Wrapper fields
  • The status, errmsg, and data fields are removed from the API v3 response.
  • All fields from data are now directly included in the root of the JSON response.
  • Added new fields errorMessage, errorCode, and errorDetail to the error response format.
• Updates to parsing logic
  • You do not have to parse the data field to access the API response data value.
  • You can directly consume field value from the root of the JSON response.
• Updates to error handling
  • Added new fields errorMessage, errorCode, and errorDetail to the error response format.
  • The error code in API v3 may differ from that in API v1 for the same API endpoint.

Examples of Success Response Format for REST API v1 and API v3

The response payload of API v1 is different from API v3, hence the parsing of response has been changed. When the API successfully fetches the response, the response format is as follows:

• API v1 success response

{
    "status": 200,
    "errmsg": "OK",
    "data": {
            <API specific data fields and value>
    }
}

• API v3 success response

{
   <API specific data, same data that we are returning in "data" field of API V1 response>
}

Examples of Error Response Format for REST API v1 and API v3

In case of error response, the format is as follows:

• API v1 error response

{
    "data": null,
    "errmsg": <ERROR_MESSAGE>,
    "status": <ERROR_CODE>
}

• API v3 error response

{
    "errorMessage": <ERROR_MESSAGE>,
    "errorCode": <ERROR_CODE>,
    "errorDetail": null
}

Comparison of Parameter Differences between REST API v1 and API v3

When migrating from API v1 to API v3, you must consider the differences in API URL, error codes, and filter syntax.

API URL Updates for REST API v1 and API v3

When migrating from API v1 to API v3, you must replace the API v1 URL with the API v3 URL. Some API URLs for components such as Collectors and Websites have changed. The mapping between the v1 and v3 URLs is given in the following table:

Error Code Updates for REST API v1 and API v3

LogicMonitor has updated some error codes in API v3. When migrating from API v1 to API v3, you must consider the API v3 error codes. The mapping between the v1 and v3 error codes is given in the following table:

Error Code Update Examples for REST API v1 and API v3

Following are the examples of API v1 and API v3 of the Processing fields. 

• API v1 Code Block

import json
  
# Success Response Handling
def handle_success_response_v1(json_response):
    response = json.loads(json_response)
    status = response['status']
    errmsg = response['errmsg']
    data = response['data']
    # Process the fields from the data object
    # Example: total = data['total']
  
# Error Response Handling
def handle_error_response_v1(json_response):
    response = json.loads(json_response)
    status = response['status']
    errmsg = response['errmsg']
    data = response['data']
    # Process the error message and status

• API v1 Code Block of Processing Fields

#!/bin/env python
  
import requests
import json
import hashlib
import base64
import time
import hmac
import getpass
  
#Account Info: LogicMonitor recommends to NEVER hardcode the credentials. Instead, retrieve the values from a secure storage.
#Note: The below is provided for illustration purposes only.
AccessId = getpass.getpass("Enter your AccessId: ")
AccessKey = getpass.getpass("Enter your AccessKey: ")
Company = 'apiAccount'
  
#Request Info
httpVerb ='GET'
resourcePath = '/device/devices/1'
fields = 'id,name,displayName'
queryParams = '?fields=' + fields
data = ''
  
#Construct URL
url = 'https://'+ Company +'.logicmonitor.com/santaba/rest' + resourcePath + queryParams
  
#Get current time in milliseconds
epoch =str(int(time.time() * 1000))
  
#Concatenate Request details
requestVars = httpVerb + epoch + data + resourcePath
  
#Construct signature
digest = hmac.new(
        AccessKey.encode('utf-8'),
        msg=requestVars.encode('utf-8'),
        digestmod=hashlib.sha256).hexdigest()
signature = base64.b64encode(digest.encode('utf-8')).decode('utf-8')
  
# Construct headers
auth = 'LMv1 ' + AccessId + ':' + str(signature) + ':' + epoch
  
# headers = {'Content-Type':'application/json','Authorization':auth}
headers = {'X-version':'1','Content-Type':'application/json','Authorization':auth}
  
#Make request
response = requests.get(url, data=data, headers=headers)
  
#body of response
response_body = json.loads(response.content.decode('utf-8'))
print ('Response Body:',response_body)
  
status = response_body['status']
if (status == 200):
    #Fetch data from body of response
    data = response_body['data']
  
    #Read device fields value from data
    device_name = data['name']
    device_displayName = data['displayName']
    print ("name:", device_name)
    print ("displayName:", device_displayName)
else:
    data = response_body['data']
    errmsg = response_body['errmsg']
    print ("Error status code:",status)
    print ("Error data:",data)
    print ("Error message:",errmsg)

• API v3 Code Block

import json
  
# Success Response Handling
def handle_success_response_v3(json_response):
    response = json.loads(json_response)
    # Process the fields directly from the response
    # Example: total = response['total']
  
# Error Response Handling
def handle_error_response_v3(json_response):
    response = json.loads(json_response)
    error_message = response['errorMessage']
    error_code = response['errorCode']
    error_detail = response['errorDetail']
    # Process the error message, code, and detail

• API v3 Code Block of Processing Fields

#!/bin/env python
  
import requests
import json
import hashlib
import base64
import time
import hmac
import getpass
  
#Account Info: LogicMonitor recommends to NEVER hardcode the credentials. Instead, retrieve the values from a secure storage.
#Note: The below is provided for illustration purposes only.
AccessId = getpass.getpass("Enter your AccessId: ")
AccessKey = getpass.getpass("Enter your AccessKey: ")
Company = 'apiAccount'
  
#Request Info
httpVerb ='GET'
resourcePath = '/device/devices/1'
fields = 'id,name,displayName'
queryParams = '?fields=' + fields
data = ''
  
#Construct URL
url = 'https://'+ Company +'.logicmonitor.com/santaba/rest' + resourcePath + queryParams
  
#Get current time in milliseconds
epoch =str(int(time.time() * 1000))
  
#Concatenate Request details
requestVars = httpVerb + epoch + data + resourcePath
  
#Construct signature
digest = hmac.new(
        AccessKey.encode('utf-8'),
        msg=requestVars.encode('utf-8'),
        digestmod=hashlib.sha256).hexdigest()
signature = base64.b64encode(digest.encode('utf-8')).decode('utf-8')
  
# Construct headers
auth = 'LMv1 ' + AccessId + ':' + str(signature) + ':' + epoch
headers = {'X-version':'3','Content-Type':'application/json','Authorization':auth}
  
#Make request
response = requests.get(url, data=data, headers=headers)
  
#body of response
print ('Response Status:',response.status_code)
response_body = json.loads(response.content.decode('utf-8'))
print ('Response Body:',response_body)
  
status = response.status_code
if (status == 200):
    #Read device fields value from response_body
    device_name = response_body['name']
    device_displayName = response_body['displayName']
    print ("name:", device_name)
    print ("displayName:", device_displayName)
else:
    errorMessage = response_body['errorMessage']
    errorCode = response_body['errorCode']
    errorDetail = response_body['errorDetail']
    print ("Error status code:",errorCode)
    print ("Error details:",errorDetail)
    print ("Error message:",errorMessage)

This article highlights the changes to LogicMonitor REST API with each version. It aims to give you a clear view of how our APIs have evolved and improved.

Updates in v224 Platform Release

In v224 Platform release, LogicMonitor has made the following updates to API v3 Swagger and SDK files.

• Addition of new Cost Optimization Recommendations endpoints
• Addition of x-minimum-permissions metadata to all endpoints

For more information, see REST API v3 Swagger Documentation. 

New Endpoints Added to API v3 Swagger and SDK Files

In v224 Platform release, LogicMonitor has updated LogicMonitor REST API v3 Swagger, v3 Python, and GO SDK files with the following new endpoints.

Display of x-minimum-permissions Metadata in API v3 Swagger

To strengthen security, LogicMonitor REST API v3 Swagger now includes the x-minimum-permissions metadata in the Extensions section of each API endpoint. This metadata specifies the minimum permission required to access the API endpoint.

Updates in v210 Platform Release

In v210 Platform release, we have updated LogicMonitor REST API v3 Swagger, v3 Python and GO SDK files with the following new endpoints.

Updates in v207 Platform Release

In v207 Platform release, we have updated LogicMonitor REST API v3 Swagger with the accessGroups and accessGroupIds fields. You can find the fields in the response of the following API endpoints:

AppliesToFunctions

GET /setting/functions

GET /setting/functions/{id}

Datasources

GET /setting/datasources

GET /setting/datasources/{id}

Updates in v201 Platform Release

Starting with Platform release v201, in addition to the existing filter _all~ you can also use a new filter description~ to search for specific data.

• _all – the filter performs full text search that is, keyword search based on username, ip, description, and sessionid fields. The response fetches the result that match the value specified in the filter across the mentioned fields. Note that you will get generic result.
  Example – {{url}}/setting/accesslogs?filter=_all~"update value=false, old value=true"
  Here, the response is as follows:
  • "update value=false, old value=true"
  • "update value=true, old value=false"
  • Any response that has update, value, false, old, value, and true in it (in any sequence). For example, "update value of field is changed to true, field old value was false"
• description – the filter performs exact text search that is, exact substring match. The search is based only on the description field. The response fetches the result that exactly match with the value specified in the description field. You will get limited but specific result.
  Example – {{url}}/setting/accesslogs?filter=description~"update value=false, old value=true"
  Here, the response is as follows:
  • "update value=false, old value=true"

Updates in v200 Platform Release

In v200 Platform release, we have updated LogicMonitor REST API v3 Swagger with the following fields:

• Instance level threshold setting – alertTransitionInterval, alertClearInterval, and alertForNoData
• Instance group level threshold setting – alertTransitionInterval, alertClearTransitionInterval, and alertForNoData
• Resource group level threshold setting – alertTransitionInterval, alertClearTransitionInterval, and alertForNoData

The impacted API endpoints are:

• GET /device/devices/{deviceId}/devicedatasources/{hdsId}/instances/{instanceId}/alertsettings
• PUT /device/devices/{deviceId}/devicedatasources/{hdsId}/instances/{instanceId}/alertsettings/{id}
• PATCH /device/devices/{deviceId}/devicedatasources/{hdsId}/instances/{instanceId}/alertsettings/{id}
• GET /device/groups/{deviceGroupId}/datasources/{dsId}/alertsettings
• PUT /device/groups/{deviceGroupId}/datasources/{dsId}/alertsettings
• PATCH /device/groups/{deviceGroupId}/datasources/{dsId}/alertsettings
• PUT /device/devices/{deviceId}/devicedatasources/{deviceDsId}/groups/{dsigId}/datapoints/{dpId}/alertconfig
• PATCH /device/devices/{deviceId}/devicedatasources/{deviceDsId}/groups/{dsigId}/datapoints/{dpId}/alertconfig

Updates in v198 Platform Release

Updates to Swagger and SDK Files

In v198 Platform release, we have updated LogicMonitor REST API v3 Swagger and v3 Python and GO SDK files. The Swagger and SDK files will be available after v198 deployment to production is complete. For any questions, contact your LogicMonitor Customer Success Manager. For details, see REST API v3 Swagger Documentation.

Refer to the following table for the new API endpoints that are added to LogicMonitor REST API v3.

Refer to the following table for the API endpoints that are removed from LogicMonitor REST API v3.

Block Access to LM REST API v4 using Bearer Token

Starting with v198 release, you will not be able to use bearer token to authenticate yourself to use LogicMonitor REST API v4 external endpoints. We have already disabled Basic and LMv1 authentication to use API v4. Note that API v4 is not officially supported. We recommend you to use LogicMonitor REST API v3.

Bearer Token Support for Python and GO SDK

You can now use Bearer token to authenticate yourself to use GO and Python v3 SDK. The SDK files will be available after v198 deployment to production is complete. For any questions, contact your LogicMonitor Customer Success Manager. For details, see LogicMonitor v3 SDK.

Additional Updates

• Due to performance issue, we removed customColumn from  /alert/alerts and /alert/alerts/id response. Similarly, we also removed detailMessage from  /alert/alerts response. However, users can still see detailMessage in /alert/alerts/id response.
• Updated deviceType description in Device model. The deviceType field value is now set to ‘0’.
• Due to performance issue, we removed customColumn request parameter from GET /alert/alerts/{id} and GET /alert/alerts

General Changes

REST API v1 and v2 Sunset Notice

We have decided to sunset LogicMonitor REST API v1 and v2. We encourage you to migrate to API v3 starting April 2023. We will continue to support API v1 and v2 until October 2024 and then stop supporting them. We will communicate the end of support date in advance to help you migrate to API v3. For more info, see LogicMonitor REST API v1 and v2 Sunset.

REST API Filters

When you call the endpoint GET /alert/alerts with filters, previously, even if there were no new alerts the result was inconsistent and shuffled. We have fixed this issue. As long as no new alert is generated or an existing one cleared, the result does not shuffle and the sequence of alerts list remains consistent. For more info, see REST API Basic Filters and REST API Advanced Filters.

LMv1 Token

Applications consume APIs and SDKs to connect with multiple backend platforms which provide tokens/secrets for authentication of the APIs and SDKs with backend platforms. To authenticate, many times users enter the secrets/tokens along with the source code leading to major security issue. As a security measure, we have now revised the token format. 

LMv1 token is dynamically built using access_id+access_key+payload+time+http_method. It is valid only for 10 minutes, thus storing it or committing in the repository serves no purpose.

• access_id – Consist of alphanumeric characters of size 20. For example, 32WDPj2KIdZikg7g98SR
• access_key – Consist of alphanumeric characters of size 120. For example, lma_A4S8)Ps9^jT9[4YFN4S36yG~+uF[h4tG){]]827McL=E3RtaqED%+{(n2p%+LOTRhYjc3ZmQtNmI2MC00M2EzLWJlZjYtMGQ3MmVhOTEwYzA3L0BeLhN  

Changes in REST API v3

Addition of numOfKuberntesDevices field

We added a numOfKuberntesDevices field to the DeviceGroup API model. It is present in the response body of all the endpoints that refer to the DeviceGroup API model. It indicates the number of Kubernetes resources in the target group. It also includes the count of Kubernetes resources in the sub groups of the target group.

Examples: 

If you select:

• A root group (id = 1) – The response body will include a count of all Kubernetes devices present in the portal.
• A specific device group – The response body will include a count of Kubernetes devices present in that device group.

New Endpoints

The major highlight of REST API v3 is the addition of five new endpoints. They are:

• POST – /setting/datasources/{id}/audit
• POST – /setting/eventsources/{id}/audit
• POST – /setting/configsources/{id}/audit
• POST – /setting/propertyrules/{id}/audit
• GET – /setting/integrations/auditlogs

For more information, see REST API v3 Swagger Documentation.

Changes in REST API v2

LogicMonitor REST API v2 includes new features, including non-backwards compatibility.

Status Codes

In REST API v1, there were two status codes for a response: HTTP status code (almost always 200), and a different LogicMonitor status code in the response body. With REST API v2, we’re returning one HTTP status code, and we’ve considerably narrowed the list of possible status codes that will be returned. 

No Basic Authentication Support

We’ve removed support for basic authentication with REST API v2. We did this to encourage more use of API tokens for authentication, as there are many additional benefits (separation of UI / API access, audit log entries, and more secure).

Support for PATCH Method

REST API v2 includes support for HTTP PATCH for most resources. You may find this useful for updating just one field of a resource, instead of having to use PUT to update the entire resource (all fields). 

Response Body Structure

In REST API v1, successful responses included status, errmsg, and data objects at the top level of the response. With REST API v2, since the HTTP status now matches the LM status, the contents of ‘data’ will be returned at the top level for a successful response. A non-successful response will include error message fields. Note that this does mean that scripts written for REST API v1 and configured to parse API response should be adjusted to reflect this.

LogicMonitor REST API v3 Swagger documentation contains a complete list of v3 API endpoints and Models related to the endpoints. You can expand each API endpoint to explore the details. It contains request and response parameters with examples and description.

• Before making API calls, you should authenticate yourself.
• You can make v3 requests by including a ‘?v=3’ query parameter or by including a ‘X-Version:3’ header.
• Properties passed in the body of an API call are case sensitive. 
• When adding cloud devices, do not use NetScan to discover cloud devices as it can lead to issues. Instead, follow the new onboarding process. For more information, see LM Cloud Monitoring Overview, Enabling Cloud Monitoring using Local Collector, and AWS Monitoring Setup.
• Offset indicates the position of a specific record in the dataset. It is the starting point of the list. For example, there is an array of 10 elements and in the API request you specify offset as 4. The API response will return result from the 5th element onwards.
• For fetching alerts, the offset limit is 10000 alerts.
• Size indicates the number of elements to return at a time in the response. For example, if you specify size=60, then the response will return result in a batch of 60. LogicMonitor REST API v3 supports maximum size of 1000 records. Even if you specify a number above 1000, the response will always return 1000 records. Example, there are 7000 alerts and you set offset=1000 and size=500. In the response, the API will return alerts from 1001 to 1500.
• In case of SDTs endpoints, the response may contain extra fields depending upon the type of SDT that you select.
• In case of Widgets endpoints, based on the widget type you select, the request and response will contain additional attributes. For more details about the attributes, refer models specific to the selected widget type at the end of the Swagger documentation.

v3 Swagger Doc

When an unsuccessful request is made, in LogicMonitor REST API v2 and v3, the response body will contain an errorCode field with one of the following codes:

Along with a data object, the response body contains a ‘status’ field which should display one of the following codes for v1 of the API:

When a REST API operation fails, an error code is provided in the response body. This can happen due to invalid or incorrect inputs or issues in the server. We use standard HTTP error codes to indicate the error in the response body. 

This table will help you understand more about errors and ways to resolve them. The following are default error messages, and can differ as per API.

Each request sent to the LogicMonitor server is made over HTTPS and thoroughly authenticated. All data is received as JSON.  LogicMonitor’s REST API supports the API token authentication method.

LogicMonitor API authentication differs as per versions.

• v1 API authentication– Supports basic authentication.

• v2 and v3 API authentication– Supports token-based authentication (LMv1 and Bearer token)

Bearer Token

The bearer token is a combination of multiple alpha numeric characters and is auto-generated by LogicMonitor. You can use bearer token to authenticate yourself to use LogicMonitor Python and GO v3 SDK files, and LogicMonitor REST API v3.

As a LogicMonitor customer, when you buy a license for a device you are eligible to get a bearer token. You do not need a specific role to get the token. It is unique for each user.

Once you get the bearer token, you must add it to the API requests just once. LogicMonitor REST API code reuses the token without you having to enter it every time. As a developer using LogicMonitor REST API, you need not develop authentication header or write commands to authenticate yourself.

To maintain secrecy of the bearer token, once you save the token, the system automatically masks some part of it with asterisks (*). For more information, see Bearer Token.

LMv1 Token

The LMv1 token-based authentication method requires that with every request you include a custom HTTP header containing:

• Your API Token Access ID

• A Base64 encoded HMAC signature based on your API Token Access Key

• A timestamp in epoch milliseconds

Specifically, you must concatenate request details to form a string, and use your Access Key to calculate the HMAC-SHA256 of that string. You then need Base64 to encode the result. 

The complete Base64 encoded HMAC signature should be in the following format:

signature = base64(HMAC-SHA256(Access Key,HTTP VERB + TIMESTAMP (in epoch milliseconds) + POST/PUT DATA (if any) + RESOURCE PATH) )

The full authentication header must be in the following format:

Authorization: LMv1 AccessId:Signature:Timestamp

How is Authentication Done?

When LogicMonitor servers receive an API request, they ensure the specified timestamp is within 30 minutes of the current time. If that requirement is satisfied, they retrieve the Access Key associated with the specified Access ID and compute the signature in the above format. The servers compare that signature to the signature included in the request. If the two signatures match, the request is authenticated, but still subject to the permissions associated with the API Token (the token Access ID and Access Key must have sufficient permission to perform the requested action). In the event that the two signatures do not match, an error will be returned.

Basic Authentication

LogicMonitor’s REST API for v1 supports HTTP Basic Authentication. To use HTTP Basic Authentication, each request must include an HTTP header with the following authentication information: Authorization:Basic `echo -n username:password | base64`

Almost all web clients support HTTP basic authentication and will construct this header for you.

In the following example, a user apiUser in account api.logicmonitor.com makes a request to update a website group.

Examples

curl --user 'apiUser:example' -H "Content-Type: application/json" -d '{"name":"newWebsiteGroup","description":"testSites","disableAlerting":false}' -X PUT "https://api.logicmonitor.com/santaba/rest/service/groups/7" -v

In the following example, a user apiUser in account api.logicmonitor.com makes a request to get all website groups.

wget --auth-no-challenge  --http-user='apiUser' --http-password='example' "https://api.logicmonitor.com/santaba/rest/website/groups"

Rate limits are imposed for requests to LogicMonitor’s REST API. Limits are assigned per endpoint and method combination. For example, requests to GET /device/devices may have a different limit than requests to POST /device/devices or requests to GET /device/devices/ID/devicedatasources. Requests that are made in excess of the rate limits will get an HTTP 429 Too Many Requests and a response containing an error. Limits are not per user, and will apply to all requests made for your account.

Rate Limit in Response Headers

Information about limits and proximity to limits is returned in the below response headers. This enables you to view the rate limits that will be imposed and adjust scripts as needed to work around them.

Rate Limiting Logic

We recommend basing any logic intended to work around rate limiting on the above headers and their values, as the limits are subject to change. For example, you may introduce logic in your script that, when rate limits have been met, waits 60 seconds before making another request. The following are examples of such logic across various languages.

Python

The following logic can be utilized in a loop using the requests module, and implements a simple timeout if the ‘X-Rate-Limit-Remaining’ header value gets to zero.

if (response.headers['X-Rate-Limit-Remaining'] == 0):
       window = response.headers['X-Rate-Limit-Window']
       time.sleep(float(window))

Ruby

The following logic can be utilized in a loop using the net http library, and implements a simple timeout if the ‘X-Rate-Limit-Remaining’ header value gets to zero.

if resp['X-Rate-Limit-Remaining'].to_i == 0
  sleep resp['X-Rate-Limit-Window'].to_i
  end

Groovy

The following logic can be utilized in a loop using the Apache http library, and implements a simple timeout if the ‘X-Rate-Limit-Remaining’ header value gets to zero.

remainingRequestsHeader = response.getHeaders('X-Rate-Limit-Remaining');
windowHeader = response.getHeaders('X-Rate-Limit-Window');
remainingRequests = remainingRequestsHeader[0].getValue();
window = windowHeader[0].getValue();
 
if (remainingRequests.toInteger() == 0){
    Thread.sleep(window.toInteger() * 1000);
    }

PowerShell

How you should work around rate limiting with PowerShell depends on how you’re making requests. The Invoke-RestMethod cmdlet throws out response headers unless an exception occurs, and as such we recommend attempting retries when an HTTP 429 is returned if using Invoke-RestMethod. For example, you could make the API request in a try catch loop, and retry if the resulting status is 429, as shown in the following code example.

(Alternately, you can use Invoke-WebRequest cmdlet and add logic based on the rate limiting response headers.)

<# Make request & retry if failed due to rate limiting #>
$Stoploop = $false
 
do {
	try {
		<# Make Request #>
		$response = Invoke-RestMethod -Uri $url -Method $httpVerb -Headers $headers
		<# Print status and body of response #>
		$status = $response.status
		$body = $response.data| ConvertTo-Json -Depth 5
		Write-Host "Status:$status"
		Write-Host "Response:$body"
		$Stoploop = $true
		}
	catch {
		if ($response.status -eq 429){
			Write-Host "Request exceeded rate limit, retrying in 60 seconds..."
			Start-Sleep -Seconds 60
			}
		else {
			Write-Host "Request failed, not as a result of rate limiting"
			$Stoploop = $true
			}
		}
	}
While ($Stoploop -eq $false)

Default Rate Limits

The following table lists the default rate limit per request type.

Rate Limit Exceptions

The following table lists the rate limit per endpoint/method request combination.