Introduction
The NinjaRMM REST API will allow you to programmatically query your NinjaRMM organizations, devices and alerts.
Authentication
Overview
The NinjaRMM REST API uses a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication. To authenticate a request, you first concatenate selected elements of the request to form a string. You then use your API secret access key to calculate the HMAC of that string. Informally, we call this process "signing the request," and we call the output of the HMAC algorithm the signature, because it simulates the security properties of a real signature. Finally, you add this signature as a parameter of the request by using the syntax described in this section.
When the system receives an authenticated request, it fetches the API secret access key that you claim to have and uses it in the same way to compute a signature for the message it received. It then compares the signature it calculated against the signature presented by the requester. If the two signatures match, the system concludes that the requester must have access to the API secret access key and therefore acts with the authority of the principal to whom the key was issued. If the two signatures do not match, the request is dropped and the system responds with an error message.
Example Authenticated Request
GET /v1/customers HTTP/1.1
Host: api.ninjarmm.com
Date: Sun, 01 May 2016 06:51:10 GMT
Authorization: NJ TF4STGMDR4H7AEXAMPLE:rEZWuXR0X1wX3autLTHIl2zX98I=Access Token
Your access token can be found in your main NinjaRMM portal, under Configuration -> Integrations -> API
See below screenshot:
The Authentication Header
Using the HTTP Authorization header is the most common method of providing authentication information. All object operations use the Authorization request header to provide authentication information.
The NinjaRMM REST API uses the standard HTTP Authorization header to pass authentication information. (The name of the standard header is unfortunate because it carries authentication information, not authorization.) Under the NinjaRMM authentication scheme, the Authorization header has the following form:
Authorization: NJ AccessKeyId:SignatureDevelopers are issued an access key ID and secret access key when they register. For request authentication, the AccessKeyId element identifies the access key ID that was used to compute the signature and, indirectly, the developer making the request.
The Signature element is the RFC 2104 HMAC-SHA1 of selected elements from the request, and so the Signature part of the Authorization header will vary from request to request. If the request signature calculated by the system matches the Signature included with the request, the requester will have demonstrated possession of the secret access key. The request will then be processed under the identity, and with the authority, of the developer to whom the key was issued.
Following is pseudogrammar that illustrates the construction of the request Signature. (In the example, n means the Unicode code point U+000A, commonly called newline).
Signature = Base64( HMAC-SHA1( YourSecretAccessKeyID, Base64( UTF-8- Encoding-Of( StringToSign ) ) ) );
StringToSign = HTTP-Verb + "n" +
Content-MD5 + "n" +
Content-Type + "n" +
Date + "n" +
CanonicalizedResource;HMAC-SHA1 is an algorithm defined by RFC 2104 - Keyed-Hashing for Message Authentication . The algorithm takes as input two byte-strings, a key and a message. For NinjaRMM API request authentication, use your secret access key (YourSecretAccessKeyID) as the key, and the UTF-8 encoding of the StringToSign as the message. The output of HMAC-SHA1 is also a byte string, called the digest. The Signature request parameter is constructed by Base64 encoding this digest.
Time Stamp Requirement
A valid time stamp (using either the HTTP Date header or an x-nj-date alternative) is mandatory for authenticated requests. Furthermore, the client timestamp included with an authenticated request must be within 15 minutes of the NinjaRMM system time when the request is received. If not, the request will fail with the RequestTimeTooSkewed error code. The intention of these restrictions is to limit the possibility that intercepted requests could be replayed by an adversary. For stronger protection against eavesdropping, use the HTTPS transport for authenticated requests.
Some HTTP client libraries do not expose the ability to set the Date header for a request. If you have trouble including the value of the 'Date' header in the canonicalized headers, you can set the timestamp for the request by using an x-nj-date header instead. The value of the x-nj-date header must be in one of the RFC 2616 formats (https://www.ietf.org/rfc/rfc2616.txt). When an x-nj-date header is present in a request, the system will ignore any Date header when computing the request signature. Therefore, if you include the x-nj-date header, use the empty string for the Date when constructing the StringToSign. See the next section for an example.
Authentication Example
The examples in this section use the (non-working) credentials in the following table.
| Parameter | Value |
|---|---|
| AccessKeyId | TF4STGMDR4H7AEXAMPLE |
| SecretAccessKey | eh14c4ngchhu6283he03j6o7ar2fcuca0example |
In the example StringToSign, formatting is not significant, and n means the Unicode code point U+000A, commonly called newline.
Example Authenticated Request
Request
GET /v1/customers HTTP/1.1
Host: api.ninjarmm.com
Date: Sun, 01 May 2016 06:51:10 GMT
Authorization: NJ TF4STGMDR4H7AEXAMPLE:rEZWuXR0X1wX3autLTHIl2zX98I=
StringToSign
GETn
n
n
Sun, 01 May 2016 06:51:10 GMTn
/v1/customersNOTE: All dates must be in one of the RFC 2616 formats (https://www.ietf.org/rfc/rfc2616.txt).
Example
Sun, 01 May 2016 06:51:10 GMTAPI Functions
Ping
Check API availability and verify your request credentials. Returns a 204 HTTP status code for a valid request.
Organizations (Customers)
GET /v1/customers
Retrieve a list of all available organizations (customers).
Example Response
[{
"id": 1,
"name": "ABC Consultants",
"description": "IT repair shop"
}, {
"id": 2,
"name": "Magic IT People",
"description": "Quick IT Helpdesk"
}]
GET /v1/customers/id
Retrieve a specific organization (customer).
Example Response
{
"id": 1,
"name": "ABC Consultants",
"description": "IT repair shop"
}Devices
GET /v1/devices
Retrieve a list of all available devices.
Example Response
NOTE: “remote_control_url” is a tokenized link to initiate a TeamViewer session. This will only populate if you have the TeamViewer integration active.
GET /v1/devices/
Retrieve a specific device.
Example Response
Alerts
GET /v1/alerts
Retrieve list of alerts. Alert responses will contain both device and customer information.
[
{
"id": 457115,
"type": "MONITOR",
"status": "WINDOWS_SERVICE_STOPPED",
"message": "'WinDefend':'Windows Defender Service' stopped.",
"severity": null,
"result": null,
"source": null,
"os_user_name": null,
"timestamp": "Sun, 15 May 2016 22:11:39 GMT",
"can_reset": false,
"device": {
"id": 1743,
"type": "AGENT",
"sub_type": "AGENT_GENERAL",
"role": "WINDOWS_WORKSTATION",
"customer_id": 107,
"parent_device_id": null,
"display_name": "DESKTOP1",
"dns_name": "DESKTOP-MHOMN54",
"system_name": "DESKTOP-MHOMN54",
"netbios_name": "DESKTOP-MHOMN54",
"last_online": "Wed, 18 May 2016 17:07:19 GMT",
"last_update": "Wed, 18 May 2016 17:07:19 GMT"
},
"customer": {
"id": 107,
"name": "Ninja TEST",
"description": "Test customer"
}
}
]GET /v1/alerts/since
Retrieve alerts since last known alert ID (). Same schema as /v1/alerts
DELETE /v1/alerts/
Reset an alert. Only alerts with can_reset can be deleted. Returns a 204 HTTP status code for a successful request.
Limits
List API
All list APIs will be limited to 10 requests for every 10-minute interval.
Entity API
All entity APIs will be limited to not less than 10 requests per minute.
Errors
Error Responses
The server will return an error with a descriptive error_message if it is unable to process your request successfully. The error message will be accompanied with an appropriate 4xx/5xx HTTP status code.
Response Fields
- error – A short string for each error type
- error_description – A human readable description of the error with details
- error_code – A unique numeric code for each error type
Types of Errors
- invalid_header – A syntactically incorrect request header was found
- missing_header – Request is missing a required header
- skewed_time – Request date is too far from current time
- not_authenticated – Invalid AccessKeyId or incorrect Signature
- invalid_id – Requested entity does not exist
- rate_limit_exceeded – A resource has been requested beyond its allowed limits
Appendix
Enumerations
All devices have a type and a sub_type. An optional role may be present where applicable. The possible values for these properties and their descriptions are listed below.
Type
- AGENT – All Windows and Mac devices
- MONITOR_SERVER – All cloud monitor devices
- NMS_SERVER – Network Management Agent responsible for monitoring your network endpoints
- NMS_TARGET – Network endpoints monitored by the Network Management Agent
SubType
- AGENT_GENERAL – All AGENT type devices will have a sub_type value of AGENT_GENERAL
- MONITOR_SERVER_GENERAL – All cloud monitor devices excluding email monitors
- MONITOR_SERVER_EMAIL – All Email cloud monitor devices
- NMS_SERVER_GENERAL – All NMS_SERVER type devices will have a sub_type value of NMS_SERVER_GENERAL
- NMS_TARGET_GENERAL – All NMS_TARGET type devices will have a sub_type value of NMS_TARGET_GENERAL
Role
All AGENT devices will have their role set to one of the following values based upon their operating system and device role.
- WINDOWS_SERVER
- WINDOWS_WORKSTATION
- MAC
- EFOLDER_IMAGEMANAGER_SERVICE
All NMS_SERVER devices will have their role set to the following.
- NMS_NETWORK_MANAGEMENT_AGENT
All NMS_TARGET devices will have their role set to one of the following values based upon device role.
- NMS_SWITCH
- NMS_ROUTER
- NMS_FIREWALL
- NMS_PRIVATE_NETWORK_GATEWAY
- NMS_PRINTER
- NMS_SCANNER
- NMS_DIAL_MANAGER
- NMS_WAP
- NMS_IPSLA
- NMS_COMPUTER
- NMS_VM_HOST
- NMS_APPLIANCE
- NMS_OTHER
- NMS_SERVER
- NMS_PHONE
- NMS_VIRTUAL_MACHINE