Authentication#
Login/logout, TOTP enrolment, named API tokens, and web/API user management.
32 operations. Roles, error format and pagination are common to the whole API — see the REST API overview.
Authentication
Use a named bearer token. Every endpoint except POST /api/v1/auth/login,
POST /api/v1/auth/enrol and GET /api/v1/system/health requires one. A super-user creates a
token with POST /api/v1/auth/tokens; the plaintext (bngtok_…) is returned exactly once at
creation and only a SHA-256 hash is stored on the appliance, so a lost token is replaced rather
than recovered. Send it on every request:
Each token carries a fixed role (read-only, operator or super-user) and is exempt from CSRF
checks. This is the single credential you need for scripts, integrations and monitoring.
Accounts and tokens share one identity model with the appliance CLI (login.users). Repeated
authentication failures lock the account/source-IP pair out temporarily (HTTP 423 on login).
Session cookies (bundled web UI only)
The appliance also accepts an interactive session cookie, which is how the bundled web UI authenticates. It is documented for completeness — API clients should not use it. It is bound to a login session and obliges the caller to manage a CSRF token, neither of which suits automation.
POST /api/v1/auth/login with username + password (and a TOTP code when enrolled) sets the
bng_session cookie and returns a csrfToken (also available from GET /api/v1/auth/whoami).
Cookie-authenticated mutating requests (anything other than GET/HEAD/OPTIONS) must also send
that value in the X-CSRF-Token header or they are rejected with 403.
NetavoBNG Management API v1#
Contact: Netavo
Authentication#
POST /api/v1/auth/enrol#
Complete a mandatory TOTP enrolment and log in.
Description
Anonymous. Follows a login that returned totpEnrolmentRequired: send the
enrolment token plus the first authenticator code. On success behaves exactly like a
successful login (session cookie + CSRF token).
Request body
Other accepted types: application/*+json, text/json
Schema of the request body
{
"required": [
"enrolmentToken",
"totpCode"
],
"type": "object",
"properties": {
"enrolmentToken": {
"type": "string",
"description": "The short-lived token returned by the login response."
},
"totpCode": {
"type": "string",
"description": "First code generated by the authenticator app for the new secret."
}
},
"description": "POST /api/v1/auth/enrol body — completes a mandatory TOTP enrolment started by login.",
"example": {
"enrolmentToken": "bngenr_5c1f0a94d27b",
"totpCode": "418244"
}
}
Responses
{
"status": "success",
"username": "noc-alice",
"role": "operator",
"csrfToken": "kR3s9Xq1TfL8vB2wYc7Nd0",
"enrolmentToken": null,
"secret": null,
"otpauthUri": null
}
Schema of the response body
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "\"success\" (logged in, cookie set), \"totpCodeRequired\" (retry login with a code),\n or \"totpEnrolmentRequired\" (enrol via POST /api/v1/auth/enrol)."
},
"username": {
"type": "string",
"description": "Logged-in username (status \"success\").",
"nullable": true
},
"role": {
"type": "string",
"description": "Effective role: \"read-only\", \"operator\" or \"admin\" (status \"success\").",
"nullable": true
},
"csrfToken": {
"type": "string",
"description": "CSRF token to send in X-CSRF-Token on cookie-authenticated mutations (status \"success\").",
"nullable": true
},
"enrolmentToken": {
"type": "string",
"description": "Short-lived token identifying this enrolment (status \"totpEnrolmentRequired\");\n echo it in POST /api/v1/auth/enrol.",
"nullable": true
},
"secret": {
"type": "string",
"description": "Base32 TOTP secret to load into an authenticator app (status \"totpEnrolmentRequired\").",
"nullable": true
},
"otpauthUri": {
"type": "string",
"description": "otpauth:// URI for QR-code enrolment (status \"totpEnrolmentRequired\").",
"nullable": true
}
},
"description": "POST /api/v1/auth/login and /enrol response. Which fields are present depends on\n string LoginResponseDto.Status; absent fields are omitted from the JSON.",
"example": {
"status": "success",
"username": "noc-alice",
"role": "operator",
"csrfToken": "kR3s9Xq1TfL8vB2wYc7Nd0",
"enrolmentToken": null,
"secret": null,
"otpauthUri": null
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/auth/login#
Log in with username/password (+ TOTP when enrolled).
Description
Anonymous. On success sets the bng_session cookie and returns the session's
csrfToken — cookie-authenticated mutating requests must echo it in the X-CSRF-Token
header. The response status field also signals the TOTP flows: totpCodeRequired means
retry login with totpCode set; totpEnrolmentRequired means the account must enrol —
load the returned secret/otpauthUri into an authenticator app and finish with
POST /api/v1/auth/enrol. Repeated failures lock the account/source-IP pair out (423).
Request body
Other accepted types: application/*+json, text/json
Schema of the request body
{
"required": [
"username",
"password",
"totpCode"
],
"type": "object",
"properties": {
"username": {
"type": "string",
"description": "Account name (shared with the appliance CLI's login.users)."
},
"password": {
"type": "string",
"description": "Account password."
},
"totpCode": {
"type": "string",
"description": "Current 6-digit TOTP code; required once the account is enrolled\n (omit on the first attempt — the response says whether a code is needed).",
"nullable": true
}
},
"description": "POST /api/v1/auth/login body.",
"example": {
"username": "noc-alice",
"password": "correct horse battery staple",
"totpCode": "418244"
}
}
Responses
{
"status": "success",
"username": "noc-alice",
"role": "operator",
"csrfToken": "kR3s9Xq1TfL8vB2wYc7Nd0",
"enrolmentToken": null,
"secret": null,
"otpauthUri": null
}
Schema of the response body
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "\"success\" (logged in, cookie set), \"totpCodeRequired\" (retry login with a code),\n or \"totpEnrolmentRequired\" (enrol via POST /api/v1/auth/enrol)."
},
"username": {
"type": "string",
"description": "Logged-in username (status \"success\").",
"nullable": true
},
"role": {
"type": "string",
"description": "Effective role: \"read-only\", \"operator\" or \"admin\" (status \"success\").",
"nullable": true
},
"csrfToken": {
"type": "string",
"description": "CSRF token to send in X-CSRF-Token on cookie-authenticated mutations (status \"success\").",
"nullable": true
},
"enrolmentToken": {
"type": "string",
"description": "Short-lived token identifying this enrolment (status \"totpEnrolmentRequired\");\n echo it in POST /api/v1/auth/enrol.",
"nullable": true
},
"secret": {
"type": "string",
"description": "Base32 TOTP secret to load into an authenticator app (status \"totpEnrolmentRequired\").",
"nullable": true
},
"otpauthUri": {
"type": "string",
"description": "otpauth:// URI for QR-code enrolment (status \"totpEnrolmentRequired\").",
"nullable": true
}
},
"description": "POST /api/v1/auth/login and /enrol response. Which fields are present depends on\n string LoginResponseDto.Status; absent fields are omitted from the JSON.",
"example": {
"status": "success",
"username": "noc-alice",
"role": "operator",
"csrfToken": "kR3s9Xq1TfL8vB2wYc7Nd0",
"enrolmentToken": null,
"secret": null,
"otpauthUri": null
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/auth/logout#
Log out the current interactive session.
Description
Invalidates the server-side session and clears the cookie. Still 200 when no session cookie is present. Any authenticated role.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
Schema of the response body
{
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "What happened: \"loggedOut\", \"enrolled\", \"created\", \"updated\", \"deleted\"."
},
"username": {
"type": "string",
"description": "The affected account, when the action targets one (omitted otherwise).",
"nullable": true
}
},
"description": "Small status-only result used by several auth actions.",
"example": {
"status": "ok",
"username": "noc-alice"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/auth/oidc/providers#
List enabled OIDC providers for the login page.
Description
Anonymous. Returns each enabled provider's name (used in the login URL) and a
displayName button label. Empty when no providers are configured.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/auth/oidc/{provider}/callback#
OIDC callback — validate the response and establish the session.
Description
Anonymous. The IdP redirects here with code + state. On success sets the
bng_session cookie and 302s to the return URL (or app root). On failure 302s to
/login?error=… so the SPA can show the reason.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
code |
query | string | No | ||
error |
query | string | No | ||
provider |
path | string | No | ||
state |
query | string | No |
Responses
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/auth/oidc/{provider}/login#
Begin OIDC login — redirect the browser to the identity provider.
Description
Anonymous. Issues a 302 to the IdP authorization endpoint with PKCE + state + nonce. returnUrl (optional, same-origin relative path only) is where the user lands after a successful callback.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
provider |
path | string | No | Provider name from `GET providers`. | |
returnUrl |
query | string | No | Same-origin relative path to return to (e.g. `/sessions`). |
Responses
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/auth/passkey/credentials#
List the current account's registered passkeys.
Description
Interactive sessions only. Returns each credential's id, label, AAGUID, transports and creation time (no secret material).
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
DELETE /api/v1/auth/passkey/credentials/{id}#
Remove one of the current account's passkeys.
Description
Interactive sessions only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
id |
path | string | No | The base64url credential id (from the credentials list). |
Responses
Schema of the response body
{
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "What happened: \"loggedOut\", \"enrolled\", \"created\", \"updated\", \"deleted\"."
},
"username": {
"type": "string",
"description": "The affected account, when the action targets one (omitted otherwise).",
"nullable": true
}
},
"description": "Small status-only result used by several auth actions.",
"example": {
"status": "ok",
"username": "noc-alice"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/auth/passkey/login/begin#
Begin a passkey login (assertion challenge).
Description
Anonymous. Optionally supply a username to scope the allow-list; omit it for
username-less (resident-key) login. Returns a ceremony id and the WebAuthn
AssertionOptions for navigator.credentials.get(). Only available when the
passkey policy is passwordless.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
Responses
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schema of the response body
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/auth/passkey/login/finish#
Finish a passkey login: verify the assertion and start a session.
Description
Anonymous. On success sets the bng_session cookie and returns the session's
csrfToken — exactly like a password login (identity source: passkey).
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Other accepted types: application/*+json, text/json
Responses
{
"status": "success",
"username": "noc-alice",
"role": "operator",
"csrfToken": "kR3s9Xq1TfL8vB2wYc7Nd0",
"enrolmentToken": null,
"secret": null,
"otpauthUri": null
}
Schema of the response body
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "\"success\" (logged in, cookie set), \"totpCodeRequired\" (retry login with a code),\n or \"totpEnrolmentRequired\" (enrol via POST /api/v1/auth/enrol)."
},
"username": {
"type": "string",
"description": "Logged-in username (status \"success\").",
"nullable": true
},
"role": {
"type": "string",
"description": "Effective role: \"read-only\", \"operator\" or \"admin\" (status \"success\").",
"nullable": true
},
"csrfToken": {
"type": "string",
"description": "CSRF token to send in X-CSRF-Token on cookie-authenticated mutations (status \"success\").",
"nullable": true
},
"enrolmentToken": {
"type": "string",
"description": "Short-lived token identifying this enrolment (status \"totpEnrolmentRequired\");\n echo it in POST /api/v1/auth/enrol.",
"nullable": true
},
"secret": {
"type": "string",
"description": "Base32 TOTP secret to load into an authenticator app (status \"totpEnrolmentRequired\").",
"nullable": true
},
"otpauthUri": {
"type": "string",
"description": "otpauth:// URI for QR-code enrolment (status \"totpEnrolmentRequired\").",
"nullable": true
}
},
"description": "POST /api/v1/auth/login and /enrol response. Which fields are present depends on\n string LoginResponseDto.Status; absent fields are omitted from the JSON.",
"example": {
"status": "success",
"username": "noc-alice",
"role": "operator",
"csrfToken": "kR3s9Xq1TfL8vB2wYc7Nd0",
"enrolmentToken": null,
"secret": null,
"otpauthUri": null
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/auth/passkey/register/begin#
Begin registering a passkey for the current account.
Description
Interactive sessions only (not bearer tokens). Returns a ceremony id and the
WebAuthn CredentialCreateOptions to pass to navigator.credentials.create();
finish with POST register/finish. Unavailable (400) when webUi.hostname is
unset or the passkey policy is off.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schema of the response body
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/auth/passkey/register/finish#
Finish registering a passkey (verify attestation, store the credential).
Description
Interactive sessions only. Send the ceremony id from register/begin,
the authenticator's attestation response, and an optional label.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Other accepted types: application/*+json, text/json
Schema of the request body
{
"required": [
"id",
"response",
"label"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ceremony id returned by `register/begin`."
},
"response": {
"$ref": "#/components/schemas/JsonElement"
},
"label": {
"type": "string",
"description": "Optional operator-facing label (\"Chris's YubiKey\").",
"nullable": true
}
},
"description": "POST body for `register/finish`."
}
Responses
Schema of the response body
{
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "What happened: \"loggedOut\", \"enrolled\", \"created\", \"updated\", \"deleted\"."
},
"username": {
"type": "string",
"description": "The affected account, when the action targets one (omitted otherwise).",
"nullable": true
}
},
"description": "Small status-only result used by several auth actions.",
"example": {
"status": "ok",
"username": "noc-alice"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/auth/providers/oidc#
List OIDC providers (client secrets never returned).
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
[
{
"name": "entra",
"enabled": true,
"displayName": "Sign in with Entra ID",
"issuer": "https://login.microsoftonline.com/9f3c1b8e-4d27-4a51-b0e6-52f7c0a91d34/v2.0",
"clientId": "1c7d5a83-b204-4f0e-9d92-8b416f2c0a3e",
"scopes": [
"openid",
"profile",
"email"
],
"usernameClaim": "preferred_username",
"groupsClaim": "groups",
"fetchUserInfo": false,
"redirectUri": "https://lns1.hul1.example.net:8443/api/v1/auth/oidc/entra/callback",
"roleMap": [
{
"match": "bng-admins",
"role": "admin"
},
{
"match": "bng-noc",
"role": "operator"
}
],
"hasClientSecret": true
}
]
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
PUT /api/v1/auth/providers/oidc/{name}#
Create or replace an OIDC provider (matched by name). Omit/blank clientSecret to keep the stored one.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
name |
path | string | No |
Request body
{
"name": "entra",
"enabled": true,
"displayName": "Sign in with Microsoft Entra ID",
"issuer": "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0",
"clientId": "6f1a3c94-2f7e-4b41-9d0a-71c5b8e3f2aa",
"clientSecret": "##SECRET-DATA##",
"scopes": [
"openid",
"profile",
"email",
"groups"
],
"usernameClaim": "preferred_username",
"groupsClaim": "groups",
"fetchUserInfo": false,
"redirectUri": "https://bng1.example.net:8443/api/v1/auth/oidc/entra/callback",
"roleMap": {
"bng-superusers": "super-user",
"bng-operators": "operator",
"bng-noc": "read-only"
}
}
Other accepted types: application/*+json, text/json
Schema of the request body
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Stable id used in the callback URL (/api/v1/auth/oidc/{name}/callback)."
},
"enabled": {
"type": "boolean",
"description": "Enabled flag; a disabled provider is not offered on the login page."
},
"displayName": {
"type": "string",
"description": "Button label on the login page (\"Sign in with Entra ID\")."
},
"issuer": {
"type": "string",
"description": "OIDC issuer (authority) URL; discovery document is at {issuer}/.well-known/openid-configuration."
},
"clientId": {
"type": "string"
},
"clientSecret": {
"type": "string",
"description": "Confidential-client secret. Write-only across API/CLI; stored like other shared secrets."
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Requested scopes; \"openid\" is always included."
},
"usernameClaim": {
"type": "string",
"description": "ID-token claim used as the session username."
},
"groupsClaim": {
"type": "string",
"description": "ID-token (or UserInfo) claim carrying group/role membership."
},
"fetchUserInfo": {
"type": "boolean",
"description": "Query the UserInfo endpoint for groups when they aren't in the ID token."
},
"redirectUri": {
"type": "string",
"description": "Explicit redirect_uri override (split-horizon DNS); else derived from webUi.hostname."
},
"roleMap": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AuthRoleRule"
},
"description": "Group/claim → role rules (fail closed on no match)."
}
},
"example": {
"name": "entra",
"enabled": true,
"displayName": "Sign in with Microsoft Entra ID",
"issuer": "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0",
"clientId": "6f1a3c94-2f7e-4b41-9d0a-71c5b8e3f2aa",
"clientSecret": "##SECRET-DATA##",
"scopes": [
"openid",
"profile",
"email",
"groups"
],
"usernameClaim": "preferred_username",
"groupsClaim": "groups",
"fetchUserInfo": false,
"redirectUri": "https://bng1.example.net:8443/api/v1/auth/oidc/entra/callback",
"roleMap": {
"bng-superusers": "super-user",
"bng-operators": "operator",
"bng-noc": "read-only"
}
}
}
Responses
Schema of the response body
{
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "What happened: \"loggedOut\", \"enrolled\", \"created\", \"updated\", \"deleted\"."
},
"username": {
"type": "string",
"description": "The affected account, when the action targets one (omitted otherwise).",
"nullable": true
}
},
"description": "Small status-only result used by several auth actions.",
"example": {
"status": "ok",
"username": "noc-alice"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
DELETE /api/v1/auth/providers/oidc/{name}#
Delete an OIDC provider.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
name |
path | string | No |
Responses
Schema of the response body
{
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "What happened: \"loggedOut\", \"enrolled\", \"created\", \"updated\", \"deleted\"."
},
"username": {
"type": "string",
"description": "The affected account, when the action targets one (omitted otherwise).",
"nullable": true
}
},
"description": "Small status-only result used by several auth actions.",
"example": {
"status": "ok",
"username": "noc-alice"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/auth/providers/passkey#
Current passkey policy.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
PUT /api/v1/auth/providers/passkey#
Set the passkey policy (off | secondFactor | passwordless).
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
Other accepted types: application/*+json, text/json
Responses
Schema of the response body
{
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "What happened: \"loggedOut\", \"enrolled\", \"created\", \"updated\", \"deleted\"."
},
"username": {
"type": "string",
"description": "The affected account, when the action targets one (omitted otherwise).",
"nullable": true
}
},
"description": "Small status-only result used by several auth actions.",
"example": {
"status": "ok",
"username": "noc-alice"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/auth/providers/tacacs#
Current TACACS+ configuration (shared secret never returned).
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"enabled": true,
"servers": [
{
"host": "10.20.2.31",
"port": 49
},
{
"host": "10.20.2.32",
"port": 49
}
],
"transportVrf": "mgmt",
"timeoutMs": 5000,
"authType": "pap",
"authorizeService": "bng",
"roleAttribute": "priv-lvl",
"roleMap": [
{
"match": "15",
"role": "admin"
},
{
"match": "5",
"role": "operator"
}
],
"perCommandAuthorizationEnabled": false,
"commandAccountingEnabled": false,
"commandAuthorizationFallback": "local",
"hasSecret": true
}
Schema of the response body
{
"required": [
"enabled",
"servers",
"transportVrf",
"timeoutMs",
"authType",
"authorizeService",
"roleAttribute",
"roleMap",
"perCommandAuthorizationEnabled",
"commandAccountingEnabled",
"commandAuthorizationFallback",
"hasSecret"
],
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"servers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebUiTacacsServer"
}
},
"transportVrf": {
"type": "string",
"nullable": true
},
"timeoutMs": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32"
},
"authType": {
"type": "string"
},
"authorizeService": {
"type": "string"
},
"roleAttribute": {
"type": "string"
},
"roleMap": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AuthRoleRule"
}
},
"perCommandAuthorizationEnabled": {
"type": "boolean"
},
"commandAccountingEnabled": {
"type": "boolean"
},
"commandAuthorizationFallback": {
"type": "string"
},
"hasSecret": {
"type": "boolean"
}
},
"description": "Admin view of the TACACS+ config — no shared secret, just whether one is set.",
"example": {
"enabled": true,
"servers": [
{
"host": "10.20.2.31",
"port": 49
},
{
"host": "10.20.2.32",
"port": 49
}
],
"transportVrf": "mgmt",
"timeoutMs": 5000,
"authType": "pap",
"authorizeService": "bng",
"roleAttribute": "priv-lvl",
"roleMap": [
{
"match": "15",
"role": "admin"
},
{
"match": "5",
"role": "operator"
}
],
"perCommandAuthorizationEnabled": false,
"commandAccountingEnabled": false,
"commandAuthorizationFallback": "local",
"hasSecret": true
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
PUT /api/v1/auth/providers/tacacs#
Replace the TACACS+ configuration. Omit/blank secret to keep the stored one.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
{
"enabled": true,
"servers": [
{
"host": "10.20.2.30",
"port": 49
}
],
"secret": "##SECRET-DATA##",
"transportVrf": "management",
"timeoutMs": 5000,
"authType": "pap",
"authorizeService": "bng",
"roleAttribute": "priv-lvl",
"roleMap": {
"15": "super-user",
"7": "operator",
"1": "read-only"
},
"perCommandAuthorizationEnabled": false,
"commandAccountingEnabled": false,
"commandAuthorizationFallback": "local"
}
Other accepted types: application/*+json, text/json
Schema of the request body
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"servers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebUiTacacsServer"
},
"description": "Ordered server list; tried in order, next on connect/timeout/error (not on auth-fail)."
},
"secret": {
"type": "string",
"description": "Shared key for RFC 8907 body obfuscation. Write-only across API/CLI. Empty = unencrypted\n bodies, refused in production config validation."
},
"transportVrf": {
"type": "string",
"description": "Linux VRF device to bind the client socket into via SO_BINDTODEVICE (like RADIUS).",
"nullable": true
},
"timeoutMs": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Per-server connect+read deadline; on total failure login falls through to local auth.",
"format": "int32"
},
"authType": {
"type": "string",
"description": "\"ascii\" (interactive GETUSER/GETPASS) or \"pap\" (single-exchange)."
},
"authorizeService": {
"type": "string",
"description": "Authorization service requested to obtain the role (default \"shell\")."
},
"roleAttribute": {
"type": "string",
"description": "AV pair used to derive the role: \"priv-lvl\" (15→admin, ≥1→operator) or a custom pair."
},
"roleMap": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AuthRoleRule"
},
"description": "Optional refinement of the role over the raw priv-lvl/attribute value."
},
"perCommandAuthorizationEnabled": {
"type": "boolean",
"description": "When true, TACACS+-authenticated CLI sessions ask the server before each command."
},
"commandAccountingEnabled": {
"type": "boolean",
"description": "When true, TACACS+-authenticated CLI sessions emit START/STOP accounting per command."
},
"commandAuthorizationFallback": {
"type": "string",
"description": "Fallback for per-command authorization ERROR/transport failure: \"local\" applies the\n appliance role check; \"deny\" refuses the command. Default local preserves break-glass behaviour."
}
},
"description": "TACACS+ (RFC 8907) operator authentication for web/API + appliance CLI login, with\n local fallback (design doc 33 §33.5).",
"example": {
"enabled": true,
"servers": [
{
"host": "10.20.2.30",
"port": 49
}
],
"secret": "##SECRET-DATA##",
"transportVrf": "management",
"timeoutMs": 5000,
"authType": "pap",
"authorizeService": "bng",
"roleAttribute": "priv-lvl",
"roleMap": {
"15": "super-user",
"7": "operator",
"1": "read-only"
},
"perCommandAuthorizationEnabled": false,
"commandAccountingEnabled": false,
"commandAuthorizationFallback": "local"
}
}
Responses
Schema of the response body
{
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "What happened: \"loggedOut\", \"enrolled\", \"created\", \"updated\", \"deleted\"."
},
"username": {
"type": "string",
"description": "The affected account, when the action targets one (omitted otherwise).",
"nullable": true
}
},
"description": "Small status-only result used by several auth actions.",
"example": {
"status": "ok",
"username": "noc-alice"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/auth/tokens#
List named API tokens.
Description
Returns each token's name and role. The token plaintext is never retrievable — it is shown exactly once at creation. Super-user only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/auth/tokens#
Create a named API token.
Description
Returns the plaintext token (bngtok_…) exactly once — store it now; the
appliance keeps only a SHA-256 hash. Use it as Authorization: Bearer bngtok_….
Super-user only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
Other accepted types: application/*+json, text/json
Schema of the request body
{
"required": [
"name",
"role"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Unique token name (shown in listings and audit logs)."
},
"role": {
"type": "string",
"description": "Role the token grants: \"read-only\", \"operator\" or \"admin\" (super-user)."
}
},
"description": "POST /api/v1/auth/tokens body.",
"example": {
"name": "prov-automation",
"role": "operator"
}
}
Responses
Schema of the response body
{
"required": [
"name",
"token"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Token name."
},
"token": {
"type": "string",
"description": "The bearer token plaintext (bngtok_…). Store it now; it cannot be\n retrieved again."
}
},
"description": "POST /api/v1/auth/tokens result — the only time the plaintext token is revealed.",
"example": {
"name": "monitoring",
"token": "bngtok_9f4c2a7e15b84d03ae6172c9d5083b41"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/auth/tokens/device#
List the caller's own device tokens.
Description
Any authenticated role. Only self-service device tokens minted for the caller are returned; named automation tokens are not shown here.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/auth/tokens/device#
Mint a bearer token for the caller's current account and role.
Description
Interactive sessions only (not bearer tokens), with CSRF. The plaintext token is returned exactly once; only a SHA-256 hash is stored. Device tokens expire after 90 days without successful use.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
Other accepted types: application/*+json, text/json
Responses
Schema of the response body
{
"required": [
"name",
"token"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Token name."
},
"token": {
"type": "string",
"description": "The bearer token plaintext (bngtok_…). Store it now; it cannot be\n retrieved again."
}
},
"description": "POST /api/v1/auth/tokens result — the only time the plaintext token is revealed.",
"example": {
"name": "monitoring",
"token": "bngtok_9f4c2a7e15b84d03ae6172c9d5083b41"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
DELETE /api/v1/auth/tokens/device/{name}#
Revoke one of the caller's own device tokens.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
name |
path | string | No |
Responses
Schema of the response body
{
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "What happened: \"loggedOut\", \"enrolled\", \"created\", \"updated\", \"deleted\"."
},
"username": {
"type": "string",
"description": "The affected account, when the action targets one (omitted otherwise).",
"nullable": true
}
},
"description": "Small status-only result used by several auth actions.",
"example": {
"status": "ok",
"username": "noc-alice"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
DELETE /api/v1/auth/tokens/{name}#
Delete a named API token.
Description
Requests using the token stop authenticating immediately. Super-user only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
name |
path | string | No | The token name (from the token list). |
Responses
Schema of the response body
{
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "What happened: \"loggedOut\", \"enrolled\", \"created\", \"updated\", \"deleted\"."
},
"username": {
"type": "string",
"description": "The affected account, when the action targets one (omitted otherwise).",
"nullable": true
}
},
"description": "Small status-only result used by several auth actions.",
"example": {
"status": "ok",
"username": "noc-alice"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/auth/totp/begin#
Begin voluntary TOTP enrolment for the current session's account.
Description
Interactive sessions only (not bearer tokens). Returns the new secret and an
otpauth:// URI to load into an authenticator app; confirm with
POST /api/v1/auth/totp/confirm to activate it. Any authenticated role.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"secret": "JBSWY3DPEHPK3PXP",
"otpauthUri": "otpauth://totp/NetavoBNG:noc-alice?secret=JBSWY3DPEHPK3PXP&issuer=NetavoBNG"
}
Schema of the response body
{
"required": [
"secret",
"otpauthUri"
],
"type": "object",
"properties": {
"secret": {
"type": "string",
"description": "Base32 TOTP secret."
},
"otpauthUri": {
"type": "string",
"description": "otpauth:// URI for QR-code enrolment."
}
},
"description": "POST /api/v1/auth/totp/begin — material for the authenticator app.",
"example": {
"secret": "JBSWY3DPEHPK3PXP",
"otpauthUri": "otpauth://totp/NetavoBNG:noc-alice?secret=JBSWY3DPEHPK3PXP&issuer=NetavoBNG"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/auth/totp/confirm#
Confirm a voluntary TOTP enrolment.
Description
Send the current authenticator code to prove the secret was captured; from then on login requires a TOTP code. Any authenticated role (interactive sessions only).
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
Other accepted types: application/*+json, text/json
Schema of the request body
Responses
Schema of the response body
{
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "What happened: \"loggedOut\", \"enrolled\", \"created\", \"updated\", \"deleted\"."
},
"username": {
"type": "string",
"description": "The affected account, when the action targets one (omitted otherwise).",
"nullable": true
}
},
"description": "Small status-only result used by several auth actions.",
"example": {
"status": "ok",
"username": "noc-alice"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/auth/users#
List accounts (web UI + CLI share one identity model).
Description
Returns each account's username, effective API role, and whether TOTP is enrolled. Super-user only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/auth/users#
Create an account.
Description
The account can log in to the web UI/API and the appliance CLI (one identity model). Committed to the appliance configuration and audited. Super-user only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
Other accepted types: application/*+json, text/json
Schema of the request body
{
"required": [
"username",
"password",
"role"
],
"type": "object",
"properties": {
"username": {
"type": "string",
"description": "New account name."
},
"password": {
"type": "string",
"description": "Initial password."
},
"role": {
"type": "string",
"description": "Role: \"read-only\", \"operator\" or \"admin\" (super-user)."
}
},
"description": "POST /api/v1/auth/users body.",
"example": {
"username": "noc-alice",
"password": "correct horse battery staple",
"role": "operator"
}
}
Responses
Schema of the response body
{
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "What happened: \"loggedOut\", \"enrolled\", \"created\", \"updated\", \"deleted\"."
},
"username": {
"type": "string",
"description": "The affected account, when the action targets one (omitted otherwise).",
"nullable": true
}
},
"description": "Small status-only result used by several auth actions.",
"example": {
"status": "ok",
"username": "noc-alice"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
PUT /api/v1/auth/users/{username}#
Update an account (password / role / clear TOTP).
Description
Only the supplied fields change; each change is committed and audited individually. Super-user only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
username |
path | string | No | The account to update. |
Request body
Other accepted types: application/*+json, text/json
Schema of the request body
{
"required": [
"password",
"role",
"clearTotp"
],
"type": "object",
"properties": {
"password": {
"type": "string",
"description": "New password, or null to keep the current one.",
"nullable": true
},
"role": {
"type": "string",
"description": "New role, or null to keep the current one.",
"nullable": true
},
"clearTotp": {
"type": "boolean",
"description": "true clears the account's TOTP enrolment (they re-enrol at next\n login when TOTP is required).",
"nullable": true
}
},
"description": "PUT /api/v1/auth/users/{username} body. Only the supplied fields change.",
"example": {
"password": null,
"role": "admin",
"clearTotp": false
}
}
Responses
Schema of the response body
{
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "What happened: \"loggedOut\", \"enrolled\", \"created\", \"updated\", \"deleted\"."
},
"username": {
"type": "string",
"description": "The affected account, when the action targets one (omitted otherwise).",
"nullable": true
}
},
"description": "Small status-only result used by several auth actions.",
"example": {
"status": "ok",
"username": "noc-alice"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
DELETE /api/v1/auth/users/{username}#
Delete an account.
Description
Removes the account from the appliance configuration (web UI/API and CLI). Deleting the last super-user is rejected. Super-user only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
username |
path | string | No | The account to delete. |
Responses
Schema of the response body
{
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "What happened: \"loggedOut\", \"enrolled\", \"created\", \"updated\", \"deleted\"."
},
"username": {
"type": "string",
"description": "The affected account, when the action targets one (omitted otherwise).",
"nullable": true
}
},
"description": "Small status-only result used by several auth actions.",
"example": {
"status": "ok",
"username": "noc-alice"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/auth/whoami#
Who am I — the authenticated identity of this request.
Description
Returns the identity name, effective role, whether the credential is an interactive session or a bearer token, and (sessions only) the CSRF token to send on mutating requests.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"username": "noc-alice",
"role": "operator",
"kind": "local",
"csrfToken": "kR3s9Xq1TfL8vB2wYc7Nd0"
}
Schema of the response body
{
"required": [
"username",
"role",
"kind",
"csrfToken"
],
"type": "object",
"properties": {
"username": {
"type": "string",
"description": "Identity name (account username or token name)."
},
"role": {
"type": "string",
"description": "Effective role: \"read-only\", \"operator\" or \"admin\"."
},
"kind": {
"type": "string",
"description": "\"session\" (cookie) or \"token\" (bearer)."
},
"csrfToken": {
"type": "string",
"description": "The session's CSRF token (null for bearer tokens).",
"nullable": true
}
},
"description": "GET /api/v1/auth/whoami — the authenticated identity of the request.",
"example": {
"username": "noc-alice",
"role": "operator",
"kind": "local",
"csrfToken": "kR3s9Xq1TfL8vB2wYc7Nd0"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
Schemas#
ApiTokenCreated#
| Name | Type | Description |
|---|---|---|
name |
string | Token name. |
token |
string | The bearer token plaintext (bngtok_…). Store it now; it cannot be retrieved again. |
ApiTokenInfo#
| Name | Type | Description |
|---|---|---|
createdUtc |
string(date-time) | null | |
device |
boolean | |
deviceUser |
string | null | |
label |
string | null | |
lastUsedUtc |
string(date-time) | null | |
name |
string | Token name. |
role |
string | Role the token grants: "read-only", "operator" or "admin". |
AuthActionResult#
| Name | Type | Description |
|---|---|---|
status |
string | What happened: "loggedOut", "enrolled", "created", "updated", "deleted". |
username |
string | null | The affected account, when the action targets one (omitted otherwise). |
AuthRoleRule#
| Name | Type | Description |
|---|---|---|
match |
string | An IdP group/claim value, a TACACS+ attribute value, or "*" (catch-all). |
role |
string | Role to grant on a match: "admin", "operator", or "readonly". |
CreateDeviceTokenRequest#
| Name | Type | Description |
|---|---|---|
label |
string | Operator-facing label for this phone/tablet/laptop. |
CreateTokenRequest#
| Name | Type | Description |
|---|---|---|
name |
string | Unique token name (shown in listings and audit logs). |
role |
string | Role the token grants: "read-only", "operator" or "admin" (super-user). |
CreateUserRequest#
| Name | Type | Description |
|---|---|---|
password |
string | Initial password. |
role |
string | Role: "read-only", "operator" or "admin" (super-user). |
username |
string | New account name. |
EnrolRequest#
| Name | Type | Description |
|---|---|---|
enrolmentToken |
string | The short-lived token returned by the login response. |
totpCode |
string | First code generated by the authenticator app for the new secret. |
JsonElement#
Type:
LoginRequest#
| Name | Type | Description |
|---|---|---|
password |
string | Account password. |
totpCode |
string | null | Current 6-digit TOTP code; required once the account is enrolled (omit on the first attempt — the response says whether a code is needed). |
username |
string | Account name (shared with the appliance CLI's login.users). |
LoginResponse#
| Name | Type | Description |
|---|---|---|
csrfToken |
string | null | CSRF token to send in X-CSRF-Token on cookie-authenticated mutations (status "success"). |
enrolmentToken |
string | null | Short-lived token identifying this enrolment (status "totpEnrolmentRequired"); echo it in POST /api/v1/auth/enrol. |
otpauthUri |
string | null | otpauth:// URI for QR-code enrolment (status "totpEnrolmentRequired"). |
role |
string | null | Effective role: "read-only", "operator" or "admin" (status "success"). |
secret |
string | null | Base32 TOTP secret to load into an authenticator app (status "totpEnrolmentRequired"). |
status |
string | "success" (logged in, cookie set), "totpCodeRequired" (retry login with a code), or "totpEnrolmentRequired" (enrol via POST /api/v1/auth/enrol). |
username |
string | null | Logged-in username (status "success"). |
OidcProvider#
| Name | Type | Description |
|---|---|---|
displayName |
string | Button label ("Sign in with Entra ID"). |
name |
string | Provider id used in the login URL (/api/v1/auth/oidc/{name}/login). |
OidcProviderAdmin#
| Name | Type | Description |
|---|---|---|
clientId |
string | |
displayName |
string | |
enabled |
boolean | |
fetchUserInfo |
boolean | |
groupsClaim |
string | |
hasClientSecret |
boolean | |
issuer |
string | |
name |
string | |
redirectUri |
string | |
roleMap |
Array<AuthRoleRule> | |
scopes |
Array<string> | |
usernameClaim |
string |
PasskeyBeginResponse#
| Name | Type | Description |
|---|---|---|
id |
string | Short-lived ceremony id; echo it on the matching `finish`. |
options |
JsonElement |
PasskeyCredential#
| Name | Type | Description |
|---|---|---|
aaguid |
string | null | Authenticator model id (AAGUID), if reported. |
createdUtc |
string(date-time) | When the passkey was registered. |
credentialId |
string | base64url credential id. |
label |
string | null | Operator-facing label, if set. |
transports |
Array<string> | Reported transports (usb, nfc, ble, internal, hybrid). |
PasskeyLoginBeginRequest#
| Name | Type | Description |
|---|---|---|
username |
string | null | Optional account name to scope the credential allow-list; omit for username-less (resident-key) login. |
PasskeyLoginFinishRequest#
| Name | Type | Description |
|---|---|---|
id |
string | The ceremony id returned by `login/begin`. |
response |
JsonElement |
PasskeyPolicy#
| Name | Type | Description |
|---|---|---|
mode |
string |
PasskeyRegisterFinishRequest#
| Name | Type | Description |
|---|---|---|
id |
string | The ceremony id returned by `register/begin`. |
label |
string | null | Optional operator-facing label ("Chris's YubiKey"). |
response |
JsonElement |
ProblemDetails#
| Name | Type | Description |
|---|---|---|
detail |
string | null | |
instance |
string | null | |
status |
||
title |
string | null | |
type |
string | null |
TacacsAdmin#
| Name | Type | Description |
|---|---|---|
authorizeService |
string | |
authType |
string | |
commandAccountingEnabled |
boolean | |
commandAuthorizationFallback |
string | |
enabled |
boolean | |
hasSecret |
boolean | |
perCommandAuthorizationEnabled |
boolean | |
roleAttribute |
string | |
roleMap |
Array<AuthRoleRule> | |
servers |
Array<WebUiTacacsServer> | |
timeoutMs |
||
transportVrf |
string | null |
TotpConfirmRequest#
| Name | Type | Description |
|---|---|---|
totpCode |
string | Current code from the authenticator app, proving the secret was captured. |
TotpEnrolment#
| Name | Type | Description |
|---|---|---|
otpauthUri |
string | otpauth:// URI for QR-code enrolment. |
secret |
string | Base32 TOTP secret. |
UpdateUserRequest#
| Name | Type | Description |
|---|---|---|
clearTotp |
boolean | null | true clears the account's TOTP enrolment (they re-enrol at next login when TOTP is required). |
password |
string | null | New password, or null to keep the current one. |
role |
string | null | New role, or null to keep the current one. |
UserInfo#
| Name | Type | Description |
|---|---|---|
role |
string | Effective API role mapped from the account's login class. |
totpEnrolled |
boolean | True when the account has an active TOTP enrolment. |
username |
string | Account name. |
WebUiOidcProviderConfig#
| Name | Type | Description |
|---|---|---|
clientId |
string | |
clientSecret |
string | Confidential-client secret. Write-only across API/CLI; stored like other shared secrets. |
displayName |
string | Button label on the login page ("Sign in with Entra ID"). |
enabled |
boolean | Enabled flag; a disabled provider is not offered on the login page. |
fetchUserInfo |
boolean | Query the UserInfo endpoint for groups when they aren't in the ID token. |
groupsClaim |
string | ID-token (or UserInfo) claim carrying group/role membership. |
issuer |
string | OIDC issuer (authority) URL; discovery document is at {issuer}/.well-known/openid-configuration. |
name |
string | Stable id used in the callback URL (/api/v1/auth/oidc/{name}/callback). |
redirectUri |
string | Explicit redirect_uri override (split-horizon DNS); else derived from webUi.hostname. |
roleMap |
Array<AuthRoleRule> | Group/claim → role rules (fail closed on no match). |
scopes |
Array<string> | Requested scopes; "openid" is always included. |
usernameClaim |
string | ID-token claim used as the session username. |
WebUiTacacsConfig#
| Name | Type | Description |
|---|---|---|
authorizeService |
string | Authorization service requested to obtain the role (default "shell"). |
authType |
string | "ascii" (interactive GETUSER/GETPASS) or "pap" (single-exchange). |
commandAccountingEnabled |
boolean | When true, TACACS+-authenticated CLI sessions emit START/STOP accounting per command. |
commandAuthorizationFallback |
string | Fallback for per-command authorization ERROR/transport failure: "local" applies the appliance role check; "deny" refuses the command. Default local preserves break-glass behaviour. |
enabled |
boolean | |
perCommandAuthorizationEnabled |
boolean | When true, TACACS+-authenticated CLI sessions ask the server before each command. |
roleAttribute |
string | AV pair used to derive the role: "priv-lvl" (15→admin, ≥1→operator) or a custom pair. |
roleMap |
Array<AuthRoleRule> | Optional refinement of the role over the raw priv-lvl/attribute value. |
secret |
string | Shared key for RFC 8907 body obfuscation. Write-only across API/CLI. Empty = unencrypted bodies, refused in production config validation. |
servers |
Array<WebUiTacacsServer> | Ordered server list; tried in order, next on connect/timeout/error (not on auth-fail). |
timeoutMs |
Per-server connect+read deadline; on total failure login falls through to local auth. | |
transportVrf |
string | null | Linux VRF device to bind the client socket into via SO_BINDTODEVICE (like RADIUS). |
WebUiTacacsServer#
| Name | Type | Description |
|---|---|---|
host |
string | |
port |
WhoAmI#
| Name | Type | Description |
|---|---|---|
csrfToken |
string | null | The session's CSRF token (null for bearer tokens). |
kind |
string | "session" (cookie) or "token" (bearer). |
role |
string | Effective role: "read-only", "operator" or "admin". |
username |
string | Identity name (account username or token name). |
Security schemes#
| Name | Type | Scheme | Description |
|---|---|---|---|
| bearerToken | http | bearer | Named API token — the recommended credential for automation. See Authentication in the API overview. |
| sessionCookie | apiKey | Interactive session cookie used by the bundled web UI. Not the integration path for API clients — use a bearer token. See Authentication in the API overview. |
Tags#
| Name | Description |
|---|---|
| Authentication | Login/logout, TOTP enrolment, named API tokens, and web/API user management. |