ContextQMD
Back to Netdata

Netdata API Permissions and Access Control Analysis

src/web/api/API_PERMISSIONS_ANALYSIS.md

2.11.015.7 KB
Original Source

Netdata API Permissions and Access Control Analysis

Verified: 2026-07-16 Purpose: Document the route ACL and HTTP_ACCESS requirements for the 68 API route registrations in a normal production DBEngine build.

The count covers 27 v3, 17 v2, and 24 v1 route-table entries. The v1 dbengine_stats entry is compiled only with ENABLE_DBENGINE; without it the inventory is 67. Root routes and the /host/<id>/... and /node/<id>/... aliases are dispatch paths, not additional API registrations.

Permission System Overview

HTTP_ACL (Access Control List)

Controls the transport/source and feature category accepted by a route:

  • HTTP_ACL_NOCHECK - Skip only the route-table ACL comparison; independent connection, coarse-dispatch, HTTP_ACCESS, bearer-derived access, and callback-local checks still apply where present
  • HTTP_ACL_API - Via HTTP/HTTPS web server (TCP port 19999)
  • HTTP_ACL_ACLK - Via ACLK only (Netdata Cloud connection)
  • HTTP_ACL_WEBRTC - Via WebRTC connection
  • HTTP_ACL_METRICS - Metrics data access category
  • HTTP_ACL_FUNCTIONS - Functions execution category
  • HTTP_ACL_NODES - Node information category
  • HTTP_ACL_ALERTS - Alerts access category
  • HTTP_ACL_DYNCFG - Dynamic configuration category
  • HTTP_ACL_REGISTRY - Registry access category
  • HTTP_ACL_BADGES - Badges generation category
  • HTTP_ACL_MANAGEMENT - Management operations category
  • HTTP_ACL_STREAMING - Streaming category
  • HTTP_ACL_NETDATACONF - Netdata configuration category

HTTP_ACCESS (Permission Flags)

Controls WHAT the authenticated user can do (capabilities):

  • HTTP_ACCESS_NONE - No route-table access bit is required; this does not bypass the other authorization layers
  • HTTP_ACCESS_SIGNED_ID - User must be authenticated
  • HTTP_ACCESS_SAME_SPACE - User and agent must be in same Netdata Cloud space
  • HTTP_ACCESS_COMMERCIAL_SPACE - Requires commercial plan
  • HTTP_ACCESS_ANONYMOUS_DATA - Can view basic metrics/data
  • HTTP_ACCESS_SENSITIVE_DATA - Can view sensitive information
  • HTTP_ACCESS_VIEW_AGENT_CONFIG - Can read agent configuration
  • HTTP_ACCESS_EDIT_AGENT_CONFIG - Can modify agent configuration
  • HTTP_ACCESS_VIEW_NOTIFICATIONS_CONFIG - Can read notifications config
  • HTTP_ACCESS_EDIT_NOTIFICATIONS_CONFIG - Can modify notifications config
  • HTTP_ACCESS_VIEW_ALERTS_SILENCING - Can read silencing rules
  • HTTP_ACCESS_EDIT_ALERTS_SILENCING - Can modify silencing rules

HTTP_USER_ROLE

Roles are authentication metadata carried with the access mask. The generic route dispatcher does not compare role ordinals: it authorizes against the required HTTP_ACCESS bits. Do not infer endpoint authorization from role names alone.

The enum values are HTTP_USER_ROLE_NONE, HTTP_USER_ROLE_ADMIN, HTTP_USER_ROLE_MANAGER, HTTP_USER_ROLE_TROUBLESHOOTER, HTTP_USER_ROLE_OBSERVER, HTTP_USER_ROLE_MEMBER, HTTP_USER_ROLE_BILLING, and HTTP_USER_ROLE_ANY.

V3 APIs (27 total) - CURRENT/LATEST

Anonymous-data APIs

These require HTTP_ACCESS_ANONYMOUS_DATA. Unauthenticated requests receive that bit only while bearer protection is disabled. Their route ACL and all earlier transport/connection gates also apply.

APIACLAccessDescription
/api/v3/dataHTTP_ACL_METRICSANONYMOUS_DATATime-series data query
/api/v3/badge.svgHTTP_ACL_BADGESANONYMOUS_DATABadge generation
/api/v3/weightsHTTP_ACL_METRICSANONYMOUS_DATAScoring engine
/api/v3/allmetricsHTTP_ACL_METRICSANONYMOUS_DATAMetrics export
/api/v3/contextHTTP_ACL_METRICSANONYMOUS_DATAContext metadata
/api/v3/contextsHTTP_ACL_METRICSANONYMOUS_DATAMulti-node contexts
/api/v3/qHTTP_ACL_METRICSANONYMOUS_DATAFull-text search
/api/v3/alertsHTTP_ACL_ALERTSANONYMOUS_DATAMulti-node alerts
/api/v3/alert_transitionsHTTP_ACL_ALERTSANONYMOUS_DATAAlert history
/api/v3/alert_configHTTP_ACL_ALERTSANONYMOUS_DATAAlert configuration
/api/v3/variableHTTP_ACL_ALERTSANONYMOUS_DATAChart variables
/api/v3/nodesHTTP_ACL_NODESANONYMOUS_DATANodes listing
/api/v3/node_instancesHTTP_ACL_NODESANONYMOUS_DATANode instances
/api/v3/stream_pathHTTP_ACL_NODESANONYMOUS_DATAStreaming topology
/api/v3/functionHTTP_ACL_FUNCTIONSANONYMOUS_DATAExecute function (permissions checked per-function)
/api/v3/functionsHTTP_ACL_FUNCTIONSANONYMOUS_DATAList functions
/api/v3/configHTTP_ACL_DYNCFGANONYMOUS_DATADynamic configuration (read/write permissions checked per-action)
/api/v3/settingsHTTP_ACL_DASHBOARDANONYMOUS_DATAUser settings (GET/PUT)

Per-route ACL bypass entries

These use HTTP_ACL_NOCHECK. Their independent access requirements remain in force: versions and progress are bearer-protected because they require HTTP_ACCESS_ANONYMOUS_DATA; the other four require no route-table access bit.

APIACLAccessDescription
/api/v3/infoHTTP_ACL_NOCHECKNONEAgent information
/api/v3/versionsHTTP_ACL_NOCHECKANONYMOUS_DATAVersion information
/api/v3/progressHTTP_ACL_NOCHECKANONYMOUS_DATAFunction progress tracking
/api/v3/stream_infoHTTP_ACL_NOCHECKNONEStreaming statistics
/api/v3/claimHTTP_ACL_NOCHECKNONEClaim status; mutation requires current session key
/api/v3/meHTTP_ACL_NOCHECKNONECurrent user info

ACLK-Only APIs (Netdata Cloud Access Required)

These require HTTP_ACL_ACLK - ONLY accessible via Netdata Cloud (ACLK):

APIACLAccessRequirementsDescription
/api/v3/rtc_offerHTTP_ACL_ACLK | ACL_DEV_OPEN_ACCESSSIGNED_ID + SAME_SPACEExact access mask shownWebRTC connection establishment
/api/v3/bearer_protectionHTTP_ACL_ACLK | ACL_DEV_OPEN_ACCESSSIGNED_ID + SAME_SPACE + VIEW_AGENT_CONFIG + EDIT_AGENT_CONFIGExact access mask shownEnable/disable bearer protection
/api/v3/bearer_get_tokenHTTP_ACL_ACLK | ACL_DEV_OPEN_ACCESSSIGNED_ID + SAME_SPACEExact access mask shownGenerate bearer token

Note: ACL_DEV_OPEN_ACCESS expands to HTTP_ACL_NOCHECK only in NETDATA_DEV_MODE; it is zero in production builds.

V2 APIs (17 total) - DEPRECATED

V2 anonymous-data APIs

APIACLAccess
/api/v2/dataHTTP_ACL_METRICSANONYMOUS_DATA
/api/v2/weightsHTTP_ACL_METRICSANONYMOUS_DATA
/api/v2/contextsHTTP_ACL_METRICSANONYMOUS_DATA
/api/v2/qHTTP_ACL_METRICSANONYMOUS_DATA
/api/v2/alertsHTTP_ACL_ALERTSANONYMOUS_DATA
/api/v2/alert_transitionsHTTP_ACL_ALERTSANONYMOUS_DATA
/api/v2/alert_configHTTP_ACL_ALERTSANONYMOUS_DATA
/api/v2/nodesHTTP_ACL_NODESANONYMOUS_DATA
/api/v2/node_instancesHTTP_ACL_NODESANONYMOUS_DATA
/api/v2/versionsHTTP_ACL_NODESANONYMOUS_DATA
/api/v2/functionsHTTP_ACL_FUNCTIONSANONYMOUS_DATA

V2 per-route ACL bypass entries

APIACLAccess
/api/v2/infoHTTP_ACL_NOCHECKANONYMOUS_DATA
/api/v2/progressHTTP_ACL_NOCHECKANONYMOUS_DATA
/api/v2/claimHTTP_ACL_NOCHECKNONE

ACLK-Only APIs

APIACLAccess
/api/v2/rtc_offerHTTP_ACL_ACLK | ACL_DEV_OPEN_ACCESSSIGNED_ID + SAME_SPACE
/api/v2/bearer_protectionHTTP_ACL_ACLK | ACL_DEV_OPEN_ACCESSSIGNED_ID + SAME_SPACE + VIEW_AGENT_CONFIG + EDIT_AGENT_CONFIG
/api/v2/bearer_get_tokenHTTP_ACL_ACLK | ACL_DEV_OPEN_ACCESSSIGNED_ID + SAME_SPACE

V1 APIs (24 total) - DEPRECATED

V1 anonymous-data APIs

APIACLAccess
/api/v1/dataHTTP_ACL_METRICSANONYMOUS_DATA
/api/v1/weightsHTTP_ACL_METRICSANONYMOUS_DATA
/api/v1/metric_correlationsHTTP_ACL_METRICSANONYMOUS_DATA
/api/v1/badge.svgHTTP_ACL_BADGESANONYMOUS_DATA
/api/v1/allmetricsHTTP_ACL_METRICSANONYMOUS_DATA
/api/v1/chartHTTP_ACL_METRICSANONYMOUS_DATA
/api/v1/chartsHTTP_ACL_METRICSANONYMOUS_DATA
/api/v1/contextHTTP_ACL_METRICSANONYMOUS_DATA
/api/v1/contextsHTTP_ACL_METRICSANONYMOUS_DATA
/api/v1/functionHTTP_ACL_FUNCTIONSANONYMOUS_DATA
/api/v1/functionsHTTP_ACL_FUNCTIONSANONYMOUS_DATA
/api/v1/configHTTP_ACL_DYNCFGANONYMOUS_DATA

Alert APIs

APIACLAccess
/api/v1/alarmsHTTP_ACL_ALERTSANONYMOUS_DATA
/api/v1/alarms_valuesHTTP_ACL_ALERTSANONYMOUS_DATA
/api/v1/alarm_logHTTP_ACL_ALERTSANONYMOUS_DATA
/api/v1/alarm_variablesHTTP_ACL_ALERTSANONYMOUS_DATA
/api/v1/variableHTTP_ACL_ALERTSANONYMOUS_DATA
/api/v1/alarm_countHTTP_ACL_ALERTSANONYMOUS_DATA

Node Info APIs

APIACLAccess
/api/v1/infoHTTP_ACL_NODESANONYMOUS_DATA
/api/v1/aclkHTTP_ACL_NODESANONYMOUS_DATA
/api/v1/dbengine_statsHTTP_ACL_NODESANONYMOUS_DATA
/api/v1/ml_infoHTTP_ACL_NODESANONYMOUS_DATA

Special APIs

APIACLAccessNotes
/api/v1/registryHTTP_ACL_NONENONECallback requires dashboard ACL for hello, registry ACL for every other action
/api/v1/manageHTTP_ACL_MANAGEMENTNONEOnly manage/health is accepted; its callback requires the management API key in X-Auth-Token

Independent Accounting

ACL and access counts are independent dimensions; NOCHECK overlaps the access columns. The ACL count is for a production build, where ACL_DEV_OPEN_ACCESS is zero.

VersionRoutesNOCHECK ACLANONYMOUS_DATA accessNONE accessSigned ACLK access
v32762043
v21731313
v12402220
Total6895576

The nine NOCHECK routes split as follows:

RouteAccessBearer effectAdditional local check
/api/v3/infoNONENone from the generic access gateNone
/api/v3/versionsANONYMOUS_DATAUnauthenticated request denied when enabledNone
/api/v3/progressANONYMOUS_DATAUnauthenticated request denied when enabledNone
/api/v3/stream_infoNONENone from the generic access gateNone
/api/v3/claimNONENone from the generic access gateRotating session key before a claim mutation
/api/v3/meNONENone from the generic access gateNone
/api/v2/infoANONYMOUS_DATAUnauthenticated request denied when enabledNone
/api/v2/progressANONYMOUS_DATAUnauthenticated request denied when enabledNone
/api/v2/claimNONENone from the generic access gateRotating session key before a claim mutation

NOCHECK is therefore not an "always public" classification. Five entries require no generic access bit, while four are protected by bearer mode.

Permission Checking Flow

Entry paths

  • Direct HTTP enters through web_client_process_url(). The global allow connections from check, socket/port ACL construction, and the coarse web-feature admission check occur before the API version dispatcher.
  • ACLK requests enter through http_api_v2() and web_client_api_request_with_node_selection() with ACLK-derived ACL and Cloud authentication headers.
  • WebRTC requests enter through webrtc_execute_api_request() and the same node-selection dispatcher with WebRTC ACLs. WebRTC is an optional build feature and is disabled by default.
  • /host/<id>/api/... and /node/<id>/api/... select a host and re-enter the same API dispatcher. They do not add route registrations or skip route authorization.

Route dispatch order

For v1, v2, and v3, web_client_api_request_vX() applies this order:

  1. web_client_ensure_proper_authorization() initializes an unauthenticated client's access to ANONYMOUS_DATA when bearer protection is off, or to NONE when bearer protection is on. Valid Cloud/bearer permissions have already been attached to the request.
  2. The route ACL is checked. HTTP_ACL_NOCHECK makes only this predicate pass.
  3. The request access mask must contain every bit required by the route. This is a bitmask containment check, not a role comparison.
  4. The callback runs and may impose further checks.

The callback-local exceptions relevant to this inventory are:

  • v1 registry: hello requires dashboard ACL; all other actions require registry ACL.
  • v1 manage: only manage/health is routed. It requires management ACL at the table and the management API key in X-Auth-Token in the health callback.
  • v2/v3 claim: the information response needs no local key, but a claim mutation requires the current rotating session key and rotates it on use or failure.
  • v1/v3 function and config: the caller's access mask is passed to the function framework, where registered functions can require additional access bits.

Configuration Impact

For direct HTTP, the relevant source configuration is:

  • [web] allow connections from: global connection admission.
  • [web] allow dashboard from: grants the dashboard feature group (METRICS, FUNCTIONS, ALERTS, NODES, and DYNCFG).
  • [web] allow badges from: grants BADGES.
  • [web] allow management from: grants MANAGEMENT.
  • [registry] allow from: grants REGISTRY.
  • Port ACLs further intersect the feature ACLs granted to the client.

The direct HTTP coarse admission check requires at least one recognized web feature before API dispatch. A NOCHECK route skips its own route-table feature comparison after that point; it does not bypass global connection admission, port ACLs, or coarse admission. ACLK and WebRTC construct their ACLs separately and do not use the direct-client IP allowlist path.

Bearer protection

Bearer protection affects all 55 routes requiring HTTP_ACCESS_ANONYMOUS_DATA, including four of the nine NOCHECK routes. An unauthenticated direct or WebRTC request has no access bits while protection is enabled and fails those routes. A valid bearer token supplies its stored role and access mask; authorization still depends on the mask.

The seven HTTP_ACCESS_NONE routes do not acquire a generic bearer requirement. The six signed ACLK registrations require their exact signed/same-space/config access masks and, in production builds, the ACLK route ACL.

Guidance for Endpoint Documentation

Each endpoint description should state independent facts rather than assign one security label:

  1. Route ACL, including the production/dev meaning of ACL_DEV_OPEN_ACCESS.
  2. Required HTTP_ACCESS bits and the resulting bearer-mode effect.
  3. Entry-path restrictions and direct HTTP allowlist mapping, where applicable.
  4. Callback-local checks for the selected action or function.

For HTTP_ACL_NOCHECK, use wording equivalent to:

This route skips the per-route ACL comparison. Connection/transport/coarse admission, the listed HTTP access requirement, bearer-derived access, and callback-local checks still apply.

Do not describe NOCHECK routes as bypassing all security, immune to bearer protection, outside all IP admission, or impossible to restrict.

Last verified: 2026-07-16