en-US/about_NinjaRmmApiTool.help.txt
|
TOPIC
about_NinjaRmmApiTool SHORT DESCRIPTION This module is a fork of the NinjaRmmApi module by Colin Cogle, with additional features and improvements. LONG DESCRIPTION NinjaRmmApiTool is an unofficial PowerShell module to interact with the NinjaRMM Public API. It includes various cmdlets for managing alerts, customers, and devices within the NinjaRMM platform. This module is forked from Colin Cogle's NinjaRmmApi module and includes additional features and improvements. This module implements version 0.1.2 of their API. Legal Disclaimers This module is in NO WAY associated with, affiliated with, developed by, or endorsed by NinjaRMM, LLC. You also use this module at your own risk. I am not responsible if running NinjaRmmApiTool somehow breaks your NinjaRMM deployment, makes your lunch taste bad, or otherwise ruins your day. Getting an API Key To get started with this module, log into NinjaRMM, then click here: https://app.ninjarmm.com/#/configuration/integrations/api (Or, to get there yourself, log in and go to your dashboard. Then, click on Configuration, Integrations, then API.) Up in the top-right corner is a link that says "Generate API Key." Click it and give your key a descriptive name. Write down the access key ID and the secret access key. You will not see the latter again! Then, in your PowerShell session, call Set-NinjaSecrets to store the API information: PS C:\> Set-NinjaSecrets -AccessKeyID "TF4STGMDR4H7AEXAMPLE" ` >> -SecretAccessKey "eh14c4ngchhu6283he03j6o7ar2fcuca0example" With that out of the way, it's time to do something actually fun. Getting Customers You can look up customer information with the Get-NinjaCustomers cmdlet. With no arguments, it returns a list of all customers. You can also use the -CustomerID parameter to fetch a specific customer. The NinjaRMM API returns your results as native PowerShell objects. Because of this, you can query and manipulate your data with native cmdlets such as Format-List, Where-Object, and Select-Object (and of course, Out-GridView): PS C:\> Get-NinjaCustomers -CustomerID 42 id name description -- ---- ----------- 42 Deep Thought PS C:\> (Get-NinjaCustomers -CustomerID 42).name Deep Thought Getting Devices You can get devices in the same manner, by using Get-NinjaDevices: PS C:\> $myComputer = Get-NinjaDevices -DeviceID 528 PS C:\> $myComputer.System | Format-List manufacturer : Hewlett-Packard name : RECEPTION-PC model : HP Z400 Workstation dns_host_name : Reception-PC bios_serial_number : 2UA1234567 serial_number : 2UA1234567 domain : WORKGROUP Working with Alerts You can get and reset alerts, too. The syntax should look very familiar by this point. PS C:\> $alertsToReviewLater = Get-NinjaAlerts -Since 3071641 PS C:\> Reset-NinjaAlert -AlertID 3071642 EXAMPLES A quick example session with NinjaRmmApiTool might look something like this: PS C:\> Set-NinjaSecrets -AccessKeyID $myKeyID -SecretAccessKey $mySAK PS C:\> $alerts = Get-NinjaAlerts PS C:\> Reset-NinjaSecrets Firstly, we put the NinjaRMM API key information into memory. Assume that, for the sake of this example, those two variables contain your actual keys. Then, you are able to run any of the cmdlets in this module. The next line saves all alerts to the variable $alerts, which you can work with later. Finally, when you're finished making API calls, it is prudent to remove the secrets from memory. NOTE Your NinjaRMM API keys are stored in cleartext in the system's environment. It is wholly possible that another process running on this system could see your access key ID and secret access key. Thus, it is good practice to call Reset-NinjaSecrets when you are finished working. This module does not store your API key information across sessions. If you need long-term storage for your key material, consider saving it to a file, copying and pasting it from a password manager, adding it to your $Profile, or storing it with the SecretManagement module. TROUBLESHOOTING NOTE This module does not do error checking. NinjaRMM's API will return an error code to the error stream, but that cannot be tested easily. You may wish to write your code like this: $result = Get-NinjaCustomer -CustomerId 42 If ($null -eq $result) { # something bad happened } Else { # do stuff } SEE ALSO To learn more about the cmdlets in this module, please read their help page either in PowerShell (Get-Help) or online (Get-Help -Online). This module contains the following cmdlets: - Get-NinjaAlerts - Get-NinjaCustomers - Get-NinjaDevices - Reset-NinjaAlert - Reset-NinjaSecrets - Set-NinjaSecrets - Set-NinjaServerLocation For more information about this module, please visit its GitHub page at: https://github.com/kalichuza/NinjaRmmApi-Tool To learn more about the NinjaRMM Public API, view the specification here: https://www.ninjarmm.com/dev-api/ or: https://ninjaresources.s3.amazonaws.com/PublicApi/0.1.2/NinjaRMM%20Public%20API%20v0.1.2.pdf |