Skip to content

feat: add support for NetBox 4.5+ v2 API tokens (Bearer auth)#500

Open
dsvetlov wants to merge 1 commit intobb-Ricardo:developmentfrom
dsvetlov:feature/netbox-4.5-v2-token-support
Open

feat: add support for NetBox 4.5+ v2 API tokens (Bearer auth)#500
dsvetlov wants to merge 1 commit intobb-Ricardo:developmentfrom
dsvetlov:feature/netbox-4.5-v2-token-support

Conversation

@dsvetlov
Copy link
Copy Markdown

@dsvetlov dsvetlov commented Apr 4, 2026

Summary

NetBox 4.5 introduced v2 API tokens with the format nbt_<key>.<plaintext>, which require the Bearer authorization keyword instead of the legacy Token keyword.

Currently, netbox-sync hardcodes Token in the Authorization header (module/netbox/connection.py), making it incompatible with v2 tokens on NetBox 4.5+.

This PR auto-detects the token version by checking the nbt_ prefix and uses the appropriate authorization keyword:

  • nbt_* tokens → Authorization: Bearer <token>
  • Legacy tokens → Authorization: Token <token> (fully backward compatible)

This matches how NetBox itself distinguishes token versions in netbox/api/authentication.py (V1_KEYWORD = 'Token', V2_KEYWORD = 'Bearer').

Changes

  • module/netbox/connection.py: Detect token version by nbt_ prefix, use Bearer or Token accordingly
  • README.md: Document v2 token support
  • settings-example.ini: Add comment about v2 token format

Test plan

  • Test with NetBox 4.5+ using a v2 token (nbt_ prefix) — sync completes successfully
  • Test with NetBox using a legacy v1 token — backward compatibility confirmed
  • Test with NetBox < 4.5 using a v1 token — no behavior change

NetBox 4.5 introduced v2 API tokens (nbt_ prefix) that require
Bearer authorization instead of Token. Auto-detect token version
by prefix and use the appropriate authorization header keyword.

- nbt_* tokens -> Authorization: Bearer <token>
- legacy tokens -> Authorization: Token <token> (backward compatible)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@bb-Ricardo bb-Ricardo changed the base branch from main to development April 4, 2026 15:05
@bb-Ricardo bb-Ricardo self-requested a review as a code owner April 4, 2026 15:05
@bb-Ricardo
Copy link
Copy Markdown
Owner

Hi, thank you. this looks good.

Would have one request: can you please add the comment from the the settings file here:

ConfigOption("api_token",
str,
description="""Requires an NetBox API token with full permissions on all objects except
'auth', 'secrets' and 'users'
""",
config_example="XYZ",
mandatory=True,
sensitive=True),

Then you can autogenerate the config with

rm settings-example.ini
./netbox-sync.py -gc settings-example.ini

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants