N-central Organizations

N-central Organizations

N-central models the MSP's world as a three-level hierarchy of org units. Almost every other object — devices, active issues, tasks, custom properties, access groups — is scoped to an org unit, so getting the hierarchy right is the first step of any workflow.

Anti-triggers

• The client's commercial record — an N-central customer is a monitoring scope, not a billing entity. The company of record is connectwise-psa-companies, autotask-crm, syncro-customers, or superops-clients.
• A Microsoft 365 tenant or an Entra OU — an N-central org unit is neither, despite the shared "organizational unit" wording; use cipp-tenants.
• Devices inside an org unit — use ncentral-devices.
• The customer scope in another RMM — NinjaOne calls the same boundary an organization and keeps its own ID space; use ninjaone-organizations.

The Hierarchy

Service Organization (SO)          — the MSP itself (usually one)
└── Customer                       — a client company
    └── Site                       — a client location (optional level)

Org Units vs Customers

"Org unit" is the umbrella type: an org unit's orgUnitType is SO, CUSTOMER, or SITE, and every one has an orgUnitId in the same ID space. The typed tools (ncentral_list_customers, ncentral_list_sites) are convenience views over that same data.

Practical rules:

• When a tool takes an orgUnitId (device listings, active issues, custom properties), any level's ID is syntactically valid — but semantics differ. Devices live at customer/site level; an SO-level query may aggregate or reject depending on the endpoint.
• Active issues can only be listed for customers and sites, not for the SO. Sweep customers in a loop rather than querying the SO.
• Use ncentral_list_org_unit_children to walk the tree top-down when building a full map (SO → customers → sites).
• Names are not unique across the tree; always carry the orgUnitId through a workflow rather than re-resolving by name.

Registration Tokens — Treat Like Credentials

ncentral_get_registration_token returns the token embedded in agent installers for that org unit. Anyone holding it can register a device into the customer's environment — treat it exactly like a password:

• Only fetch it when the user explicitly needs it (agent deployment).
• Never write it to files, tickets, or chat logs; paste it directly to the user and say nothing more.
• Tokens expire and can be regenerated in the UI; if one leaks, tell the user to rotate it there.

Custom Properties

Custom properties are typed key/value fields attached at two levels:

MSPs use them as the glue layer: PSA company IDs, billing codes, patch rings, backup policies, onboarding status. Patterns that matter:

• Properties are defined at the SO or customer level and valued per org unit or device — a property can exist but be empty for a given target. Empty is a finding, not an error.
• Updates (ncentral_update_*_custom_property) overwrite the value with no history. Echo the current value before writing and confirm bulk updates with the user.
• Automation policies and filters in N-central often key off custom property values — changing one can silently change which policies apply to a device. Mention this when updating properties that look policy-related (e.g. "Patch Ring", "Maintenance Group").
• Property IDs are stable per server; property names are what humans know. List first, resolve name → propertyId, then get/update.

Best Practices

• Cache the org tree (IDs + names) at the start of a multi-customer workflow instead of re-listing per step.
• For "across all customers" questions, iterate customers explicitly and aggregate — report per-customer, then the rollup.
• When the user says "customer X", resolve by name via ncentral_list_customers and confirm if more than one match.

Related Skills

• api-patterns - auth, pagination, preview endpoints
• devices - device listings scoped by org unit
• monitoring-tasks - per-customer active-issue sweeps