If you’re building automations that call NinjaOne’s API or pulling data in from tools like Microsoft Defender or Tenable, you need somewhere to run those scripts and somewhere to store the credentials they use. Running that from a random workstation or from your own technician account is how credentials end up leaking or getting used in ways you can’t easily track.
An API server solves this problem. It’s a dedicated Windows device, isolated in its own organization and role, holding your API credentials in secure custom fields that only System Administrators can see. This guide walks through setting one up from scratch.
NinjaOne API server requirements
You’ll need:
- A device or VM running Windows. Physical, HyperV VM, or cloud VM all work, the operating system is what matters.
- System Administrator access in NinjaOne.
- A clear list of which services you want this server to interact with (NinjaOne’s API at minimum, plus anything else like Defender or Tenable).
The one hard requirement: nobody but your NinjaOne system administrators should have access to this device. It’s going to hold credentials with system administrator-level permissions.
Step-by-step: Setting up your API server
Step 1: Create a dedicated organization
Create a new organization to house your API server. This keeps it fully separated from your other organizations, so it doesn’t show up mixed in with real customer or endpoint data.
To create a new organization:
Click the “+” in the top right > select Organization > name it something like “API Server” > click Save in the top right.
Step 2: Create a custom device role
Navigate to Administration > Devices > Roles.
Click on Windows Systems to expand it > hover over Windows Server (or Windows Desktops and Laptops, if your API server runs Windows 11) and click the three dots > click Add child role.
Name the role “API Server” and create it under the parent that matches your operating system.
Step 3: Create secure custom fields
Still inside the Roles page, on the left side go to Device custom fields and create three new fields, all using the Secure field type.
Click Add custom field > select Secure > in the label enter “NinjaOne Instance.”
On the left navigate to Permissions > set Automations to Read Only > set API to None > set All technicians Access to Editable > click Submit.
Repeat exactly as above for the following two fields, changing only the labels:
- NinjaOne Client ID
- NinjaOne Client Secret
Label these exactly as written above. NinjaOne converts the label into a camelCase field name automatically, and that name is case-sensitive when you reference it later in a script.
Set the API permission to None on all three fields. There’s no reason for API-level access to a field storing the credentials that authenticate your API calls in the first place.
Tip: If you plan to pull data from other services like Defender or Tenable, repeat this process and create dedicated secure custom fields for each one’s credentials.
Step 4: Assign the fields to your role
Navigate back to Roles on the left side > expand Windows Systems > expand your parent role > find API Server and click the three dots on the right > click Edit.
Click Manage Tabs in the top right > click Add tab and create a new tab (for example, “API Credentials”) > once created, click the dropdown in the top right and switch to the new tab > on the left search bar type “NinjaOne” > add the three secure custom fields created in Step 3 > click Save Changes in the top right.
Step 5: Build and apply your policy
Navigate to Policies > click Add Agent policy > name it “API Server” > for the Role select the Windows Server (or Windows Desktop) role you created the custom role under > click Create > once opened, click Close in the top right.
Next, navigate to Organizations > select your API Server organization > click Policies on the left > find the row for API Server and select the dropdown > assign the policy you just created > click Save in the top right > once saved, click Close.
Step 6: Create an automation category
In Administration, go to Library > click Automation on the left > select the Categories tab > click Create category on the far right > name it something like “API Scripts” > click Create.
This keeps your API-related scripts organized and gives you a category you can later lock down to only System Administrators.
Step 7: Install the agent
Download the NinjaOne Agent installer for your API Server organization and run it on your dedicated device or VM. Alternatively, if you’re repurposing an existing device, move it into the API Server organization, update its role, and confirm the API Server policy is applied through the new assignment.
In NinjaOne, click the “+” sign in the top right > click Device > click Computer > select your API Server organization and the API server role > click Generate Installer > then download the installer or copy the link and run it on your device.
Wait for the device to fully register before moving on.
If you are repurposing an existing device, this can be done from the Device Search Grid:
In the left blue navigation pane, select the Devices tab > on the device list, find the existing device > click the toggle box next to the device name > click Edit > click Organization/Location and switch to the API Server organization > click Update
With the device still selected, click Edit > click Device Role and choose the custom API role > click Update.
With the device still selected, click Edit > click Policy and choose the API Server policy > click Update.
Step 8: Create API credentials
Once your device is connected, go to Administration > Apps > API and click Add client app in the top right.
Select API Services (machine-to-machine) and build a client app with:
- Scopes: Monitoring and Management
- Grant Type: Client credentials
- Redirect URL: leave empty
Click Add. NinjaOne will generate a client ID and client secret.
Step 9: Populate your custom fields
Copy the client ID and client secret from the app you just created > navigate to your API Server device > hover over the custom tab and select the API Credentials tab > click the edit icon on the far right > paste the client ID and client secret into the corresponding fields.
For the instance field, enter your NinjaOne region (found on the login URL):
- app.ninjarmm.com or us2 for US instances
- ca.ninjarmm.com for Canada instances
- eu.ninjarmm.com for Europe instances
- oc.ninjarmm.com for Asia-Pacific Southeast instances
- jp.ninjarmm.com for Japan instances
- fed.ninjarmm.com for FedRAMP Moderate instances
Tip: These field names are case-sensitive once converted to camelCase (ninjaoneClientId, ninjaoneClientSecret, ninjaoneInstance). If your scripts reference the fields and pull back nothing when ran, check that the labels match exactly.
Once your credentials are populated and tested, go back to Administration > Devices > Device custom fields > search “ninjaone” and click on the field name(s) to change the All-technicians Access permission on all three fields from Editable back to Read Only, so the values can’t be altered after setup.
Step 10: Lock down technician access
This is the step that makes the setup secure. Without it, any technician can view credentials with system administrator level access.
Go to Administration > Accounts > Technician Roles.
For every technician role that shouldn’t have access (in most cases, all of them except system administrators):
Click the desired role to open the editor > navigate to Organizations on the left.
- Under Organizations, set the API Server organization to No Access.
- Under Devices, set the API Server role to No Access.
- Under Policies, set the API Server policy to No Access.
- Under the automation library, set your API Scripts category to No Access
How to verify your API server configuration Once you’re done, you should have:
- A dedicated organization holding one device, your API server.
- A custom role with secure fields storing your client ID, client secret, and instance.
- A policy applied only to that organization.
- A locked automation category for your API scripts.
- Every non-admin technician role blocked from viewing the organization, device role, policy, and automation category.
If a level 1 technician can navigate to the API Server organization and see anything, go back to Step 10.
Why this matters
API credentials with client credentials grant type carry real weight. Depending on the scopes you select, whoever holds them can read and write data across your entire NinjaOne environment. Storing those credentials in a plain custom field on a shared device, or leaving them visible to every technician, turns a useful automation setup into a liability.
Building a dedicated API server takes maybe twenty minutes the first time. What you get in return is a clean, auditable structure: one place for credentials, one policy that governs them, and a technician permission model that keeps the whole thing locked down. Once it’s built, adding a new integration is just a matter of creating a few more custom fields and dropping the script in your API Scripts category.
A few examples of what this setup gets used for:
Importing vulnerability data from Microsoft Defender, so scan results land directly in NinjaOne instead of living in a separate console.
Microsoft Defender vulnerability import
Windows OS patch reporting, pulling patch status across your environment into a consolidated view.
Windows OS patch reporting
Patch status sync, keeping patch data current between NinjaOne and another source of truth rather than relying on manual checks.
Patch status sync
