Authentication

NetBox supports two token formats. The SDK handles both transparently.

---

Token versions

v2 (default)v1 (legacy)

NetBox 4.x issues v2 tokens in two parts: a key prefix and a secret suffix, combined as nbt_<key>.<secret>.

from netbox_sdk import Config

cfg = Config(
    base_url="https://netbox.example.com",
    token_version="v2",
    token_key="abc123",         # the part after "nbt_"
    token_secret="def456xyz",   # the secret suffix
)

The Authorization header sent to NetBox will be:

Bearer nbt_abc123.def456xyz

Older NetBox instances use a single opaque token:

cfg = Config(
    base_url="https://netbox.example.com",
    token_version="v1",
    token_secret="abcdef1234567890abcdef1234567890abcdef12",
)

The Authorization header will be:

Token abcdef1234567890abcdef1234567890abcdef12

---

Automatic v2 → v1 fallback

If your configuration specifies v2 but the NetBox instance rejects the Bearer token with "Invalid v2 token", the client automatically retries with the v1 Token <secret> header. This handles instances that have v1 tokens stored but are accessed with v2 config.

---

Auth header helpers

from netbox_sdk.config import authorization_header_value, resolved_token

cfg = Config(base_url="...", token_version="v2", token_key="k", token_secret="s")

resolved_token(cfg)              # "nbt_k.s"
authorization_header_value(cfg)  # "Bearer nbt_k.s"

---

Profile storage

The SDK stores named connection profiles at ~/.config/netbox-sdk/config.json (or $XDG_CONFIG_HOME/netbox-sdk/config.json).

If you already have a historical netbox-cli config file, the SDK still reads it automatically until a new NetBox SDK config is written.

from netbox_sdk.config import (
    load_profile_config,
    save_profile_config,
    clear_profile_config,
    DEFAULT_PROFILE,
)

# Load the "default" profile (applies env var overrides automatically)
cfg = load_profile_config()
cfg = load_profile_config(DEFAULT_PROFILE)   # same thing

# Save a custom profile
save_profile_config("production", cfg)
save_profile_config("staging", staging_cfg)

# Load a named profile (no env var overrides applied)
staging = load_profile_config("staging")

# Remove a profile
clear_profile_config("staging")

File security

The config directory is created with mode 0o700 and the config file with 0o600 to prevent other users on the same system from reading your credentials.

---

Environment variable overrides

For the default profile only, these environment variables override values from disk:

Variable	Config field
NETBOX_URL	base_url
NETBOX_TOKEN_KEY	token_key
NETBOX_TOKEN_SECRET	token_secret

Environment variables take precedence over stored values. Useful for CI/CD:

NETBOX_URL=https://netbox.example.com \
NETBOX_TOKEN_KEY=mykey \
NETBOX_TOKEN_SECRET=mysecret \
python your_script.py

from netbox_sdk.config import load_config

cfg = load_config()   # picks up the environment variables

---

Validating configuration

from netbox_sdk.config import is_runtime_config_complete

if not is_runtime_config_complete(cfg):
    print("Missing base_url or token credentials")

This checks that base_url, token_secret, and (for v2) token_key are all present.

---

URL normalization

The base_url field is normalized on assignment:

• Adds https:// if no scheme is given
• Strips trailing slashes
• Rejects embedded credentials (user:pass@host)
• Rejects non-HTTP schemes (ftp://, file://)
• Rejects query strings and fragments

from netbox_sdk.config import normalize_base_url

normalize_base_url("netbox.example.com")         # "https://netbox.example.com"
normalize_base_url("http://netbox.example.com/") # "http://netbox.example.com"
normalize_base_url("ftp://netbox.example.com")   # raises ValueError