How to access the NetBox API with a token

Objective

On an OVHcloud On-Prem Cloud Platform (OPCP), the NetBox web interface is protected by Keycloak SSO. A dedicated API endpoint lets an external system — for example your own CMDB or a helpdesk integration — query the NetBox inventory automatically. This endpoint authenticates directly with a NetBox API token and does not go through Keycloak.

This guide explains how to enable the dedicated endpoint, create a NetBox API token, reach the NetBox API through that endpoint, and make changes to your inventory without conflicting with the automation.

Requirements

• The dedicated API endpoint must be enabled on your platform. It is disabled by default; enabling it is the first step below.
• Access to the NetBox web interface (netbox.<your-platform-domain>), reachable through Keycloak SSO.
• A NetBox user allowed to create API tokens.
• If you also plan to make manual changes in NetBox, write access to the NetBox web interface — see IAM rights management for the required role.

Instructions

1. Enabling the dedicated API endpoint

The dedicated endpoint is disabled by default. To enable it, set the following flag in your OPCP configuration:

netbox_api:
  enabled: true

Then apply the configuration by running, from a controller:

opcp-cli deploy --system

2. Creating a NetBox API token

1. Log in to the NetBox web interface at https://netbox.<your-platform-domain> with your usual Keycloak credentials or SSO.
2. Open the user menu (top right), then click API Tokens.
3. Click Add a Token, adjust the options if needed (expiry, allowed IP ranges, read-only or write access), then save.
4. Copy the generated token and store it in a safe place. It grants access to the NetBox API with your own permissions.

For the full description of tokens and their options, see the official NetBox documentation: NetBox REST API — Tokens.

3. Calling the API through the dedicated endpoint

The dedicated endpoint exposes the NetBox API at the following URL:

https://netbox-api.<your-platform-domain>/api

Unlike the web interface, this endpoint does not use Keycloak: authentication relies entirely on your NetBox token, passed in the Authorization header of every request.

To verify that your token and the endpoint work, query the NetBox status. A valid token returns an HTTP 200 response with a JSON payload:

curl -sS -H "Authorization: Token YOUR_TOKEN" \
  https://netbox-api.<your-platform-domain>/api/status/

Once the connection is confirmed, you can query any NetBox resource, for example the list of devices:

curl -sS -H "Authorization: Token YOUR_TOKEN" \
  https://netbox-api.<your-platform-domain>/api/dcim/devices/

A request sent without a valid token is rejected. The web interface remains available only on https://netbox.<your-platform-domain>, behind Keycloak.

4. Interacting with your NetBox instance safely

Parts of your NetBox inventory may be managed automatically from the OPCP Infrastructure as Code (IaC) configuration. The following explains how to identify those objects and make changes without conflicting with the automation.

How NetBox is organised

Your NetBox instance contains two kinds of objects:

• Objects managed automatically. These carry the automation-managed tag. They are created and kept in sync with the OPCP IaC configuration. You do not need to maintain them.

• Objects managed by you. These do not carry the automation-managed tag. They are yours: create, edit, delete, retag, comment — whatever your workflow requires.

The automation-managed tag is the single signal that tells you which side an object belongs to. When in doubt, check the tag.

Making changes

The method to modify an object depends on whether it is automation-managed.

For objects without the automation-managed tag:

Edit these objects directly in the NetBox UI as usual. The automation does not touch these objects.

For objects with the automation-managed tag:

These are driven by the OPCP IaC configuration.

The Automation State tenant

The Tenancy section of NetBox contains a tenant named Automation State (slug: automation-state). This tenant holds internal bookkeeping used by the automation.

Quick reference

What to expect during normal operation

• Changelog entries from the automation account after each successful run.
• A short-lived branch named initializer-automation. It is created, used, and merged (or removed) by the automation.
• The automation-managed tag present on many objects.
• The Automation State tenant present in your tenant list.

References

• NetBox REST API
• NetBox REST API — Tokens
• How to see the node inventory

Go further

For training or technical assistance implementing our solutions, contact your sales representative or visit our Professional Services page to request a quote and have your project analysed by our experts.

Join our community of users.