About

This module is a PowerShell wrapper for the NinjaOne API. It is designed to make it easy to interact with the NinjaOne API from PowerShell.

Installing

This module is published to the PowerShell Gallery. You can install it using the following command:

Install-Module -Name NinjaOne

From time-to-time, preview releases will be published to the PowerShell Gallery. These are not considered stable and should not be used in production. You can install preview releases using the following command:

Install-Module -Name NinjaOne -AllowPrerelease

Updating

You can update the module from the PowerShell Gallery using the following command:

Update-Module -Name NinjaOne

If you want to update to the latest preview release you can use the following command:

Update-Module -Name NinjaOne -AllowPrerelease

After updating you should re-import the module in any open PowerShell sessions using the following commands:

Remove-Module -Name NinjaOne
Import-Module -Name NinjaOne

Getting Started

The first and probably most important requirement for this module is getting it connected to NinjaOne.

Creating an application in NinjaOne

1. In NinjaOne head to Administrations > Apps > API

2. Select Add on the right-hand side to add a new API application.

3. Select the Application Platform. It's important to decide what the best platform is for your needs as each offers different types of authentication and will be aimed at a particular use case.

4. Enter the Name.
   For example NinjaOne PS Module.

5. If you're going to need to use Interactive Authentication then you'll need to enter a Redirect URI. You will need to use interactive authentication to access any endpoint that acts in a user's context. This is required to run scripts, access ticket boards and access various other endpoints.

6. Select the required Scopes The monitoring scope is required to read information from NinjaOne, the management scope is required to write information to NinjaOne and the control scope is required for remote access via the API.

7. Select the required Allowed Grant Types Authorization code is required for interactive authentication, client credentials is required for non-interactive authentication and refresh token is required to refresh an expired access token (usually used in conjunction with authorization code).

8. Save your new API application. When you save you'll be presented with your Client Secret please store this securely and note that you will not be able to retrieve it again.

9. After saving you can copy your Client ID from the list of API applications.

Connecting to NinjaOne

Once you have created an API application in NinjaOne you can connect to NinjaOne using the commandlet Connect-NinjaOne.

First we'll create a hashtable containing the required parameters for Connect-NinjaOne. This example uses the Authorization Code grant type which is used for interactive authentication and connects to the EU instance of NinjaOne.

$ConnectNinjaOneParams = @{
    UseWebAuth = $True
    Instance = 'eu'
    ClientID = '00000000-0000-0000-0000-000000000000' 
    ClientSecret = '00000000-0000-0000-0000-000000000000'
    Scopes = @('monitoring', 'management')
    RedirectURL = 'http://localhost:8080'
    Port = 8080
    ShowTokens = $True
}

We can use this hashtable to connect to NinjaOne using the following command:

Connect-NinjaOne @ConnectNinjaOneParams

This uses the hashtable splatting operator (@) to pass the hashtable to the Connect-NinjaOne commandlet. To learn more about splatting see about_Splatting.

For more detailed examples of how to use Connect-NinjaOne, including using other authentication types see Connect-NinjaOne.

Running a command

Once you have connected to NinjaOne you can run commands against the API. For example, to get a list of all devices in NinjaOne you can use the following command:

Get-NinjaOneDevices

This will return a list of all devices in NinjaOne. For more detailed examples of how to use Get-NinjaOneDevice see Get-NinjaOneDevice.

Known Issues

Many NinjaOne API endpoints require the use of a user's context. If you attempt to use these endpoints without interactive authentication you will receive an error similar to the following:

Line | 28 | throw ('This function is not available when using client_cred … | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | This function is not available when using client_credentials authentication. If this is unexpected | please report this to [email protected].