Skip to main content

NinjaRMM → Halo PSA GUID Sync — Setup & Operations

Overview

This page documents the setup and ongoing operation of the automated GUID sync between NinjaRMM and Halo PSA. The sync reads the DTC Org GUID custom field from each NinjaRMM organization and writes it to the DTC Client GUID custom field in Halo PSA for all active clients.

Reference Ticket: Halo Ticket #1141374

Why This Exists

Each client org in NinjaRMM has a unique GUID stored in a custom field called DTC Org GUID. This GUID needs to be available in Halo PSA under the DTC Information tab so it can be used for cross-platform automation and identification. This integration syncs it automatically on a weekly schedule.

Components

Halo PSA API Application

  • Name: NinjaRMM GUID Sync
  • Location: Configuration > Integrations > HaloPSA API
  • Auth Method: Client ID and Secret (Services)
  • Login Type: Agent — Integrator Agent (SSO accounts are incompatible with client credentials flow)
  • Permissions: All enabled
  • Client ID: 25542a6d-2d0e-4093-bf82-e11edc64faf6
  • Client Secret: Stored in 1Password

NinjaRMM API Application

  • Name: Halo GUID Sync
  • Location: Administration > Apps > API
  • Platform: API Services (machine-to-machine)
  • Scopes: Monitoring, Management
  • Grant Type: Client Credentials
  • Client ID: 0S1xEjce1FQp7Rbn_GJTrSWTp64
  • Client Secret: Stored in 1Password

PowerShell Script

Scheduled Task

  • Location: NinjaRMM > Administration > Scheduled Tasks
  • Name: Halo GUID Sync
  • Schedule: Weekly

How the Script Works

  1. Authenticates to both NinjaRMM and Halo PSA APIs using client credentials
  2. Pulls all organizations from NinjaRMM
  3. For each org, reads the dtcOrgGuid custom field
  4. Searches Halo PSA for a matching client using a three-tier matching strategy:
    • Exact name match — preferred
    • Fuzzy word overlap match — 60% word overlap threshold
    • Manual name mapping table — for clients where names differ significantly between systems
  5. Writes the GUID to Halo PSA using the CFDtcClientGuid field
  6. Outputs a summary of all updated, skipped, and failed clients

Adding Manual Name Mappings

Fixing Name Mismatches Between Ninja and Halo

When the script reports ⚠️ No Halo match for 'Client Name', it means the client exists in Halo but under a different name. The correct fix is to update the client name in NinjaRMM to match exactly what Halo has — not the other way around.

Step 1 — Find the Client's Exact Name in Halo

  1. Log into Halo PSA at psa.dtctoday.com
  2. In the left navigation click Customers > Clients
  3. Use the search bar at the top to search for the client by a keyword (e.g. part of their name)
  4. Click on the matching client
  5. Note the exact name shown at the top of the client record — this is what Halo uses as the official name

Step 2 — Update the Name in NinjaRMM

  1. Log into NinjaRMM at app.ninjarmm.com
  2. Go to Administration > Organizations
  3. Search for the client
  4. Click into the org and click Edit
  5. Update the Organization Name field to match exactly what Halo shows
  6. Click Save

Step 3 — Re-run the Sync

Run the script again from PowerShell or wait for the next scheduled run. The client will now match and the GUID will sync successfully.

Note: Always use Halo's naming as the source of truth. Halo is the primary PSA and its client names should be considered canonical.

Adding a New Client

When a new client is onboarded:

  1. Make sure they are created in both NinjaRMM and Halo PSA
  2. Ensure the DTC Org GUID custom field is populated in NinjaRMM
  3. The weekly scheduled task will automatically sync the GUID to Halo on the next run
  4. If needed immediately, run the script manually from PowerShell

Credentials

All API credentials are stored in 1Password under the entry:

Halo/NinjaRMM API - GUID Sync Secret

CredentialLocation
Halo Client ID1Password — Halo/NinjaRMM API - GUID Sync Secret
Halo Client Secret1Password — Halo/NinjaRMM API - GUID Sync Secret
Ninja Client ID1Password — Halo/NinjaRMM API - GUID Sync Secret
Ninja Client Secret1Password — Halo/NinjaRMM API - GUID Sync Secret

Do not store plaintext credentials anywhere outside of 1Password or the NinjaRMM script variables.

Credentials

All API credentials are stored in 1Password under the entry:

Halo/NinjaRMM API - GUID Sync Secret

CredentialLocation
Halo Client ID1Password — Halo/NinjaRMM API - GUID Sync Secret
Halo Client Secret1Password — Halo/NinjaRMM API - GUID Sync Secret
Ninja Client ID1Password — Halo/NinjaRMM API - GUID Sync Secret
Ninja Client Secret1Password — Halo/NinjaRMM API - GUID Sync Secret

Do not store plaintext credentials anywhere outside of 1Password or the NinjaRMM script variables.

Troubleshooting

Issue Resolution
invalid_client on Halo auth Regenerate client secret in Halo > Configuration > Integrations > HaloPSA API > NinjaRMM GUID Sync. Ensure Integrator Agent is set as the login agent — SSO accounts will not work
invalid_client on Ninja auth Verify client ID and secret in Ninja > Administration > Apps > API > Halo GUID Sync
Client showing ⚠️ No Halo match Client name differs between systems — add a manual mapping to the $nameMappings table in the script
GUID not showing in Halo after update Verify field name is CFDtcClientGuid — this is the internal name, not the display label
Scheduled task not running Check NinjaRMM > Administration > Scheduled Tasks and verify the target device is online
Back to top