--- title: "How to access the NetBox API with a token" description: "Find out how to enable the dedicated NetBox API endpoint on your OPCP, create a NetBox API token and query the NetBox REST API without Keycloak" url: https://docs.ovhcloud.com/de/guides/hosted-private-cloud/opcp/netbox-api-access lang: en lastUpdated: 2026-10-16 --- > For AI agents: the complete documentation index is available at https://docs.ovhcloud.com/de/llms.txt, the full documentation bundle is available at https://docs.ovhcloud.com/de/llms-full.txt. # 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.** :::info This feature is available from **OPCP Core 3.0.7**. ::: ## 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.`), 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](https://docs.ovhcloud.com/de/guides/hosted-private-cloud/opcp/iam-rights-management.md) 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: ```yaml netbox_api: enabled: true ``` Then apply the configuration by running, from a controller: ```bash opcp-cli deploy --system ``` :::info In OVHcloud-managed mode, ask your OVHcloud contact to enable this endpoint if you are not able to run the deployment yourself. ::: ### 2. Creating a NetBox API token 1. Log in to the NetBox web interface at `https://netbox.` 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](https://netboxlabs.com/docs/netbox/integrations/rest-api/#tokens). ### 3. Calling the API through the dedicated endpoint The dedicated endpoint exposes the NetBox API at the following URL: ```console https://netbox-api./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: ```bash curl -sS -H "Authorization: Token YOUR_TOKEN" \ https://netbox-api./api/status/ ``` Once the connection is confirmed, you can query any NetBox resource, for example the list of devices: ```bash curl -sS -H "Authorization: Token YOUR_TOKEN" \ https://netbox-api./api/dcim/devices/ ``` A request sent without a valid token is rejected. The web interface remains available only on `https://netbox.`, behind Keycloak. :::tip This endpoint is meant for programmatic access. To browse the API interactively (the browsable API, or the Swagger and ReDoc pages), use the main NetBox interface at `https://netbox./api/`, which is served through Keycloak. ::: :::warning A token carries the permissions of the user who created it. Keep it secret, prefer a token with the narrowest scope required (read-only whenever possible), and rotate it regularly. ::: ### 4. Interacting with your NetBox instance safely :::info The `automation-managed` tag is applied from **OPCP Core 3.1**. ::: 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. :::warning Do not remove the `automation-managed` tag from objects that carry it: the automation adds it back on its next run and reverts your changes to the object. Do not add it to objects you create yourself either: the automation then takes them over and may overwrite or delete them. ::: #### 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. :::info If you edit a field managed by the OPCP IaC configuration on an `automation-managed` object directly in NetBox, the next automation run will revert your change. The OPCP IaC configuration is authoritative for these objects. ::: #### 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. :::warning Do not delete the `Automation State` tenant, and do not edit its custom fields (`automation_non_taggable_state` and `initializer_sot_hash`). Modifying or deleting them will cause the automation to misbehave on its next run. ::: #### Quick reference | Action | Allowed? / Outcome | | -------------------------------------------------------------------------------------- | ----------------------------------------------- | | Edit an object without the `automation-managed` tag | Yes | | Add journal entries, comments, or other tags on any object | Yes | | Edit a field on an `automation-managed` object that the OPCP IaC configuration manages | Will be reverted on the next run | | Delete an object with the `automation-managed` tag | Will be recreated on the next run | | Remove the `automation-managed` tag from an object | Will be added again on the next run | | Add the `automation-managed` tag to an object you created | Causes the automation to overwrite or delete it | #### 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](https://netboxlabs.com/docs/netbox/integrations/rest-api/) - [NetBox REST API — Tokens](https://netboxlabs.com/docs/netbox/integrations/rest-api/#tokens) - [How to see the node inventory](https://docs.ovhcloud.com/de/guides/hosted-private-cloud/opcp/how-to-see-node-inventory.md) ## Go further For training or technical assistance implementing our solutions, contact your sales representative or visit our [Professional Services](https://www.ovhcloud.com/de/professional-services/) page to request a quote and have your project analysed by our experts. Join our [community of users](https://community.ovhcloud.com/).