Before you begin
- A Atlas AVD plan. The Integrations hub is not available on Community
- The Administrator role in Atlas to connect, configure or disconnect a connector. Integrations appears under Administration only for administrators
- A tenant selected in the tenant picker. Credentials are stored encrypted per tenant, so each tenant you manage connects its own account
- A NetBox API token with Write enabled turned off, for a user who can view sites, tenants and devices
- NetBox reachable at a public https address with a publicly trusted certificate, or a NetBox Cloud instance
- To sync into Vault: a Vault admin and at least one asset template (the Network Device template is a good fit)
What you can do
- Document every device in a NetBox site or tenant (switches, routers, firewalls, access points, servers and the rest) as an Atlas Vault asset, with no manual data entry.
- Map each NetBox site, or each tenant, to the customer company it belongs to.
- Keep the documentation current: every hour Atlas adds new devices, updates changed details and archives devices that are no longer in NetBox.
- See what changed and when: name, serial number, asset tag, model, role, management IP, site, location, rack, rack unit and tenant changes, each with the previous value kept.
- Ask Atlas Advisor about documented equipment, for example "list the switches documented in NetBox".
Step 1: Create a read-only API token
- In NetBox, open your user menu and choose API Tokens, then Add a token. Leave Write enabled turned off so the token can only read.
- Create the token for a user who can view sites, tenants and devices. A dedicated read-only user is best. Copy the token when NetBox shows it.
- If you set Allowed IPs on the token, include the address Atlas connects from.
- Both classic tokens and the newer tokens starting with nbt_ (NetBox 4.5 and later) work.
Step 2: Connect in Atlas
Once connected, the card shows Manage, which opens Atlas Vault → Assets, and Disconnect. The token is stored encrypted and is never shown again.
- Select the tenant in the tenant picker.
- Go to Administration → Integrations and click Connect on the NetBox card.
- Enter your NetBox address, for example https://netbox.example.com or your NetBox Cloud address. You can paste the address of any NetBox page; Atlas keeps the root. If NetBox runs under a path such as https://tools.example.com/netbox, include the path.
- Paste the API token.
- Click Connect. Atlas reads your NetBox site list before saving anything; if the token or address is rejected, nothing is stored.
Atlas only connects to public addresses. A NetBox that resolves to a private or internal address, or that is not served over https with a publicly trusted certificate, is refused. Publish NetBox at a public https address or use NetBox Cloud.
Step 3: Map each site or tenant to a company
Add one sync per site or tenant. Each can be mapped only once in an Atlas tenant. Map a customer either by its NetBox tenant or by its sites, not both, so no device is documented twice. When your customers live in separate Atlas tenants, connect NetBox in each tenant.
- Open Atlas Vault → Assets → RMM & PSA sync and click Add sync.
- Source: NetBox.
- Device type: pick a site or a tenant. Sites are listed as Site: name (with the site's tenant in brackets when it has one), tenants as Tenant: name. Pick a tenant when one customer spans several sites.
- Template: pick Network Device. Atlas fills in the field mappings for you: Name, Type (from the NetBox device role), Manufacturer, Model, Serial Number, Management IP and Location (site, location and rack). You can change or add any mapping.
- Company: the customer this site or tenant belongs to.
- Leave Sync automatically every hour on, click Save Changes, then click Run now to document it straight away.
What gets documented
- Identity: name, serial number, asset tag, manufacturer, model, platform and description.
- Type: the NetBox device role. Roles that name a switch, router, firewall, access point, load balancer or gateway also fill the Network Device template's Type.
- Network: the primary IP address, the primary IPv4 and IPv6 addresses, and the out-of-band address.
- Operational: the NetBox status, such as active, planned or offline.
- Placement: site, location, rack, rack unit and face, and tenant, plus a link to the device's page in NetBox.
Each device is matched by its NetBox ID, which never changes while the device exists in NetBox. Renaming it, re-racking it, moving it to another site or correcting its serial number updates the same asset instead of creating a new one. The serial number is documented but is not used for matching, because NetBox does not require it to be unique. A device you delete and re-create in NetBox becomes a new asset. Interfaces, cables, IP prefixes, circuits and virtual machines are not documented.
Your own documentation is kept
Atlas only fills the fields you map. Notes, attachments, custom fields and anything else you add in Vault are yours and are never touched. If you edit a mapped field by hand, Atlas keeps your value; if NetBox later reports something different, the field is flagged under Drift to review so you can choose which to keep. A device that leaves NetBox is archived, not deleted, and comes back automatically if it returns. Atlas archives a device only after a complete read, so an outage or a rejected token never empties your documentation.
Change history
Open an asset's ⋯ menu and choose History to see what changed: when the device was first documented, a new name, serial number, asset tag, model, role, management IP, site, location, rack, rack unit or tenant (each with the previous and new value), when it was no longer in NetBox, and when it came back. Status changes are not recorded. The same entries appear on the Operations Timeline.
Ask Atlas Advisor
Atlas Advisor answers questions from the documented assets, read-only and limited to what you can see in Vault, with or without an AI provider. For example: "list the switches documented in NetBox", "Which NetBox devices are in Vault?" or "Is NetBox connected?".
What the integration does not do
- It is read-only. It never creates, changes or deletes anything in NetBox.
- It does not document interfaces, cables, IP prefixes, circuits or virtual machines.
- It syncs every hour or when you click Run now; the interval cannot be changed.
- It connects one NetBox token per Atlas tenant. Credentials cannot be edited in place: disconnect and connect again with the new token.
GCC High tenants
On a tenant or deployment in Azure Government (GCC High), calls to NetBox are blocked by default, because they can carry VM, host-pool and tenant names to a service outside the Government boundary. Connect fails with an Azure Government (GCC High) egress boundary message and nothing is stored, and pages that read from NetBox stay empty. The operator who runs your Atlas deployment can approve NetBox as a destination that is allowed to receive that data; once approved, the connector works normally. Running in Azure Government does not by itself make a third-party integration GCC High or CMMC compliant.
Disconnecting
Click Disconnect on the card and confirm. Atlas deletes its stored copy of the API token and pauses every Atlas Vault sync from NetBox. The documented assets and their history stay in Vault; turn the syncs back on after you reconnect. Nothing changes in NetBox. Delete the token there too if you no longer need it.
Troubleshooting
- The connection test says NetBox rejected the credentials: the token is wrong, expired or deleted, its user cannot view sites, or Allowed IPs on the token does not include Atlas.
- The connection test says the server URL is not allowed: the address resolves to a private or internal address, or is not https. Use NetBox's public https address or NetBox Cloud.
- The connection test cannot connect: check the address is right and that NetBox presents a publicly trusted certificate.
- A site or tenant is missing from the Device type list: the token's user cannot view it. Give the user permission, then add the sync again.
- A sync fails for one site or tenant: NetBox could not return its devices, for example because NetBox was unreachable. The documentation is kept until the next successful sync.
- A sync reports the integration is not configured: NetBox was disconnected. Connect it again, then turn the sync back on.