NetBox

Network Management

Overview

The NetBox connector integrates with NetBox, an open-source infrastructure resource modeling (IRM) platform for network and data center operations. The connector synchronizes virtualization, device, and IPAM data — virtual machines, devices, clusters, prefixes (subnets), and VLANs — from a NetBox instance into Brinqa.

Data retrieved from NetBox

Connector Object	Required	Maps to Data Model
Virtual Machine	Yes	Host
Device	Yes	Device
Subnet	Yes	Subnet
Cluster	Yes	Cluster
Virtual LAN	Yes	Virtual LAN

Model relationships

note

For detailed steps on how to view the data retrieved from NetBox in the Brinqa Platform, see How to view your data.

Setup

Connection settings

When setting up a data integration, select NetBox from the Connector dropdown and provide the following:

Setting	Required	Default	Description
Server URL	Yes	https://<server_url>	NetBox server URL.
API token	Yes	—	NetBox API token.
Page size	No	100	Maximum number of records to get per API request.
Parallel requests	No	min(4, available processors)	Maximum number of parallel API requests.
Custom headers	No	—	Custom HTTP headers to include with request (e.g., HeaderName=HeaderValue). Entries separated by semicolon.

Authentication

The connector authenticates with NetBox using an API token issued from the NetBox UI.

Method

Method	Description
API Token	Static token sent in the Authorization header on every request

Connection Test Endpoint

The connector validates credentials and connectivity by issuing a single paginated request against the clusters endpoint:

Method	URL
GET	/api/virtualization/clusters?offset=1&limit=1

A 2xx response confirms the base URL and API token are valid.

Request Headers

Header	Value
Authorization	Token <apiToken>
Accept	application/json

Usage

All API requests include the token in the Authorization header:

Authorization: Token <apiToken>
Accept: application/json

Obtaining a Token

In NetBox, navigate to User Profile → API Tokens → Add a token. For the public demo instance, log in with admin / admin at https://demo.netbox.dev/ and generate a token under the admin profile.

Required Privileges

The token must have read access to the following NetBox object types: virtual machines, devices, clusters, prefixes, and VLANs.

---

Sync Behavior

The connector supports incremental (delta) syncs. It maintains a sync token between runs and applies it as an incremental timestamp filter, so each run re-processes only the records that changed after the previous sync. The initial run retrieves the complete data set; later runs are incremental. The specific timestamp field applied to each object is documented under that object's Sync Duration Parameter.

How to obtain NetBox credentials

Generate a NetBox API token

For the NetBox connector to use the NetBox API, you must provide an API token. To generate a new token, follow these steps:

1. Log in to your organization's NetBox server.

2. Click your user profile in the upper-right corner of the page, and then click API Tokens.

3. Click Add a token and fill in the fields as shown below:

   • Key: Give your new token a key. If you don't provide a key, NetBox generates one automatically.

   • Write enabled: A NetBox API token can be used to perform all actions via the API that a user is permitted to do via the web UI. As Brinqa only requires read operations, uncheck this box to restrict API requests made with the token to read operations (GET) only.

   • Expires: Set an expiration date and time for the token.

   • Description: Provide a description for the token.

   • Allowed IPs: Specify any Internet Protocol (IP) v4 or v6 addresses allowed by the token. Leave this field blank if there are no restrictions.

4. Click Create.

   A new API token appears on the API Tokens page. You can view this token later without restrictions, eliminating the need to save it immediately to a secure location. However, it is still important to protect the token and limit access to authorized personnel.

Note: For additional information on managing API tokens for your NetBox account and API permissions, see NetBox documentation.

Data & mappings

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

Virtual Machine

Source Field Name	SDM Attribute
cluster.id / cluster.name	CLUSTER_ID / CLUSTER_NAME
comments	COMMENTS
created	FIRST_SEEN
derived from primary IPs	PUBLIC_IP_ADDRESSES
derived from primary IPs	PRIVATE_IP_ADDRESSES
description	DESCRIPTION
device.id	DEVICE_ID
device.name	DEVICE_NAME
disk	DISK
display	DISPLAY
id	UID
last_updated	LAST_SEEN
last_updated	SOURCE_LAST_MODIFIED
memory	MEMORY
name	NAME
name	HOSTNAMES
platform.id / platform.name	PLATFORM_ID / PLATFORM_NAME
primary_ip, primary_ip4, primary_ip6	IP_ADDRESSES
role.id / role.name	ROLE_ID / ROLE_NAME
site.id / site.name	SITE_ID / SITE_NAME
static	CATEGORIES
status.label	STATUS
tags[].name	TAGS
tenant.id / tenant.name	TENANT_ID / TENANT_NAME
url	URL
vcpus	VCPUS

Device

Source Field Name	SDM Attribute
airflow.value	AIRFLOW
asset_tag, tags[].name	TAGS
cluster.id / cluster.name	CLUSTER_ID / CLUSTER_NAME
comments	COMMENTS
created	FIRST_SEEN
derived from primary IPs	PUBLIC_IP_ADDRESSES
derived from primary IPs	PRIVATE_IP_ADDRESSES
description	DESCRIPTION
device_role.id / device_role.name	DEVICE_ROLE_ID / DEVICE_ROLE_NAME
device_type.id / device_type.model	DEVICE_TYPE_ID / DEVICE_TYPE_NAME
display	DISPLAY
face.value	FACE
id	UID
last_updated	LAST_SEEN
last_updated	SOURCE_LAST_MODIFIED
location.id / location.name	LOCATION_ID / LOCATION_NAME
name (falls back to display)	NAME
parent_device.id	PARENT_DEVICE
platform.id / platform.name	PLATFORM_ID / PLATFORM_NAME
position	POSITION
primary_ip, primary_ip4, primary_ip6	IP_ADDRESSES
rack.id / rack.name	RACK_ID / RACK_NAME
serial	SERIAL_NUMBER
site.id / site.name	SITE_ID / SITE_NAME
static	CATEGORIES
status.value	STATUS
tenant.id / tenant.name	TENANT_ID / TENANT_NAME
url	URL
vc_position	VC_POSITION
vc_priority	VC_PRIORITY
virtual_chassis.id / virtual_chassis.name	VIRTUAL_CHASSIS_ID / VIRTUAL_CHASSIS_NAME

Subnet

Source Field Name	SDM Attribute
_depth	DEPTH
children	CHILDREN
comments	COMMENTS
created	FIRST_SEEN
description	DESCRIPTION
display	NAME
family.label	FAMILY_LABEL
id	UID
is_pool	IS_POOL
last_updated	LAST_SEEN
last_updated	SOURCE_LAST_MODIFIED
mark_utilized	MARK_UTILIZED
prefix	PREFIX
role.id / role.name	ROLE_ID / ROLE_NAME
site.id / site.name	SITE_ID / SITE_NAME
static	CATEGORIES
status.value	STATUS
tags[].name	TAGS
tenant.id / tenant.name	TENANT_ID / TENANT_NAME
url	URL
vlan.id / vlan.name	VLAN_ID / VLAN_NAME
vrf.id / vrf.name	VRF_ID / VRF_NAME

Cluster

Source Field Name	SDM Attribute
comments	COMMENTS
created	FIRST_SEEN
description	DESCRIPTION
device_count	DEVICE_COUNT
display	DISPLAY
group.id / group.name	GROUP_ID / GROUP_NAME
id	UID
last_updated	LAST_SEEN
last_updated	SOURCE_LAST_MODIFIED
name	NAME
site.id / site.name	SITE_ID / SITE_NAME
status.value	STATUS
tags[].name	TAGS
tenant.id / tenant.name	TENANT_ID / TENANT_NAME
type.id / type.name	TYPE_ID / TYPE_NAME
url	URL
virtualmachine_count	VIRTUAL_MACHINE_COUNT

Virtual LAN

Source Field Name	SDM Attribute
comments	COMMENTS
created	FIRST_SEEN
description	DESCRIPTION
display	DISPLAY
group.id / group.name	GROUP_ID / GROUP_NAME
id	UID
l2vpn_termination.l2vpn.id / .name	L2VPN_ID / L2VPN_NAME
last_updated	LAST_SEEN
last_updated	SOURCE_LAST_MODIFIED
name	NAME
prefix_count	PREFIX_COUNT
role.id / role.name	ROLE_ID / ROLE_NAME
site.id / site.name	SITE_ID / SITE_NAME
status.value	STATUS
tags[].name	TAGS
tenant.id / tenant.name	TENANT_ID / TENANT_NAME
url	URL
vid	VID

Operations & API

Operations & API

Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).

Virtual Machine

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Virtual Machine on every run and applies no incremental date filter.

API

• Type: REST · Endpoint: GET /api/virtualization/virtual-machines

Device

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Device on every run and applies no incremental date filter.

API

• Type: REST · Endpoint: GET /api/dcim/devices

Subnet

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Subnet on every run and applies no incremental date filter.

API

• Type: REST · Endpoint: GET /api/ipam/prefixes

Cluster

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Cluster on every run and applies no incremental date filter.

API

• Type: REST · Endpoint: GET /api/virtualization/clusters

Virtual LAN

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Virtual LAN on every run and applies no incremental date filter.

API

• Type: REST · Endpoint: GET /api/ipam/vlans

Changelog

Changelog

The NetBox connector has undergone the following changes:

Version	Description	Migration Steps
3.0.2	Bug Fixes - Virtual LAN: the L2VPN name was being written into the L2VPN ID field. It now populates the dedicated "L2Vpn name" attribute, and "L2Vpn ID" keeps only the identifier. - Corrected the data type of reference/ID attributes that were declared as numbers but actually hold the source system's string identifiers — including Site ID, Group ID, Cluster ID, Role ID, Tenant ID, Platform ID, Type ID, Device type/role ID, Location ID, Rack ID, Virtual chassis ID, Device ID, Parent device, VRF ID, VLAN ID, VID, and L2VPN ID. They are now stored as text, so the values are no longer dropped or coerced. - Subnet: corrected the "Vlan name" attribute from a numeric type to text. - Corrected the data type of timestamp attributes — First seen, Last seen, and Source last modified — on the Cluster, Virtual Machine, Subnet, Virtual LAN, and Device models. They are now stored as proper timestamps instead of numeric epoch values, so date-based filtering, sorting, and display behave correctly.	• Cluster, Virtual Machine, Subnet, Virtual LAN, Device: the ID/reference attributes and timestamp attributes listed above, plus Virtual LAN "L2Vpn name" and Subnet "Vlan name", changed type or target. Re-sync the NetBox connector to repopulate these records with the corrected values.
3.0.1	New Features - Added support for custom HTTP headers, allowing administrators to include additional headers (e.g., for reverse proxies or custom authentication gateways) on every API request to NetBox. Improvements - Devices and virtual machines now sync multiple hostnames and public IP addresses per record, where previously only a single value was captured. This gives a more complete view of network identity for assets with multiple interfaces or DNS aliases.	• Device: The PUBLIC_IP_ADDRESS identifier attribute has been replaced by the multi-valued PUBLIC_IP_ADDRESSES. — Action: re-sync the Device data source so the new attribute is populated and identity matching uses the updated identifier. • Virtual Machine: The HOSTNAME and PUBLIC_IP_ADDRESS identifier attributes have been replaced by the multi-valued HOSTNAMES and PUBLIC_IP_ADDRESSES. — Action: re-sync the Virtual Machine data source so the new attributes are populated and identity matching uses the updated identifiers.
3.0.0	Overview The NetBox connector integrates with NetBox to synchronize network infrastructure inventory — virtual machines, physical devices, clusters, IP subnets, and virtual LANs — giving a unified asset view of the environment documented in NetBox. Category: Network Management Models	N/A