InfluxDB collects the sensor readings, machine metrics and plant telemetry that operations teams rely on, and every read and write is authorised by an API token, so token design and network exposure decide how well that data is protected. InfluxDB OSS v2 and InfluxDB 3 (Core and Enterprise) both use bearer tokens with an all-powerful operator token at the top, both listen on all interfaces unless you tell them otherwise, and both support TLS natively. This guide explains how the token model works in each version, how to contain the operator token, how to scope tokens for Telegraf agents, gateways and dashboards, which settings to change for production and what to monitor. It is written for OT and IoT platform owners, SREs and security architects running self-managed InfluxDB, and it goes deeper than the general Database Security Guide.
This is an independent guide from NHI Mgmt Group, based on InfluxData's public documentation as of November 2026. It is not sponsored or reviewed by InfluxData. Product features change, so confirm settings against InfluxData's current documentation.
Key takeaways
- The operator token is a root credential. In v2 it grants full access to all organisations; in InfluxDB 3 the
_adminoperator token never expires and cannot be deleted. Store it offline in a vault and use narrower tokens for daily work. - Scope every token to the job. In v2 use Read/Write tokens limited to specific buckets; in InfluxDB 3 Enterprise use database tokens such as
db:telemetry:writewith an expiry. Give each agent and dashboard its own token. - Change the default bind address. v2 listens on
:8086and InfluxDB 3 on0.0.0.0:8181by default. Bind to a private interface and firewall the port from OT and corporate networks alike. - Turn on TLS and the hardening options. Set
tls-certandtls-key, keep the minimum at TLS 1.2 or raise it to 1.3, and in v2 enablehardening-enabled,strong-passwordsand token hashing. - Keep authentication on in InfluxDB 3. Authentication is enabled by default; never run production with
--without-auth, and enable the admin token recovery listener only when needed, on loopback.
How identity and access work in InfluxDB
Both major versions authenticate API calls with tokens sent in the Authorization header, but they organise access differently.
InfluxDB OSS v2
v2 has users, organisations, buckets and API tokens. A user gets access to data by being a member of an organisation and holding a token; every token belongs to a user and carries permissions within that user's organisation. The setup process creates the first user, organisation, bucket and an operator token, either with a value you supply (influx setup --token) or one InfluxDB generates and saves in the active influx CLI configuration. Interactive users can also log in to the UI with a password, which creates a session.
InfluxDB 3 Core and Enterprise
InfluxDB 3 starts with authentication enabled. The first admin token you create is the operator token, named _admin. Clients send tokens as Authorization: Bearer; v1-compatible endpoints accept the token as the password in Basic or u/p query parameters, and the v2-compatible /api/v2/write endpoint accepts Authorization: Token. The CLI reads the token from INFLUXDB3_AUTH_TOKEN or --token.
| Token | Version | Scope | Use it for |
|---|---|---|---|
| Operator token | v2 | Full read and write on all organisations and resources; some operations such as reading server configuration need it | Break-glass and creating other operator tokens |
| All Access token | v2 | Full read and write on all resources in one organisation | Day-to-day administration of one organisation, as the docs recommend |
| Read/Write token | v2 | Read, write or both on specific buckets | Telegraf agents, gateways, dashboards, applications |
Operator token _admin | 3 Core and Enterprise | Full administrative access; cannot be edited or deleted, never expires, can be regenerated | Break-glass and creating named admin tokens |
| Named admin token | 3 Core and Enterprise | Full admin permissions, with an optional expiry | Named administrators and automation, with expiry set |
| Database token | 3 Enterprise | read, write on listed databases, for example db:plant1,plant2:read,write, with --expiry | Writers and readers of telemetry |
| System token | 3 Enterprise | System resources such as runtime statistics and health endpoints | Monitoring tools |
Decision guidance: on InfluxDB 3 Core, every token is an admin token, so isolation comes from separate instances per trust zone, short expiries on named admin tokens and strong network controls; plan Enterprise where you need per-database tokens for many writers. On v2, the Read/Write token gives per-bucket scoping, so the main design work is one bucket per data domain and one token per writer. Small sites with a single collector can run one write token and one read token; larger estates with many plants or tenants should map organisations or databases to sites and automate token issuance.
Admin roles and privileged access
- Contain the operator token: after setup, store the v2 operator token or the InfluxDB 3
_admintoken in a vault and stop using it for routine work. In v2 create an All Access token per organisation for administration, which the docs recommend to avoid accidental cross-organisation changes; in InfluxDB 3 create named admin tokens with an expiry for each administrator or pipeline. - Rotate the InfluxDB 3 operator token: regenerate it with
influxdb3 create token --admin --regenerateor the/api/v3/configure/token/admin/regenerateendpoint. The previous token stops working immediately and the server stores only a SHA-512 hash of the new one, so update dependent scripts in the same change window. - Plan token recovery: in v2,
influxd recovery authon the host creates a new operator token when none is available. In InfluxDB 3,--admin-token-recovery-http-bindstarts an unauthenticated recovery listener (default127.0.0.1:8182when enabled) that shuts down after one regeneration. Enable it only during recovery and keep it on loopback. Both paths make host access the real privileged boundary, so manage server logins through your Privileged Access Management Guide process. - Automated deployments: InfluxDB 3 supports an offline admin token file (
--admin-token-file) generated withinfluxdb3 create token --admin --offline --expiry ..., and Enterprise supports--permission-tokens-filefor resource tokens. Generate these files in your pipeline with a short expiry, deliver them through your secrets tooling and remove them from disk after first start. - User passwords and sessions (v2): enable
strong-passwords(at least eight characters from three of four character classes), keepsession-length(default 60 minutes) appropriate for your operators, and considersession-renew-disabledso sessions end at the set length.
Integrations, API tokens and service accounts
Most InfluxDB tokens are held by machines: Telegraf agents on edge gateways, stream processors, Grafana data sources, alerting jobs and replication between edge and central instances. Treat each as a non-human identity with an owner.
- One token per writer: give each gateway, site or collector its own write-only token on its own bucket or database. A token found on one device then exposes one data stream, and revoking it does not interrupt other sites.
- Read-only for dashboards: dashboards and reporting tools need read access only. Create separate read tokens and never reuse a writer's token for queries.
- Set expiry: InfluxDB 3 named admin tokens and Enterprise resource tokens accept
--expiry; use it, and keep a rotation calendar for v2 tokens, which you replace by creating a new token, rolling clients and deleting the old one. - Token hashing (v2): from 2.9.0 tokens are stored hashed by default (available but off in 2.8, controlled by
use-hashed-tokens), so a copy of the database file does not reveal usable tokens. Capture any plaintext token you still need, including the operator token used byinflux restore --full, before the first 2.9.0 start, since hashed tokens cannot be read back; the restore then takes--operator-token. - Secrets used by Flux tasks (v2): passwords and keys used by tasks and notification endpoints live in the secret store, set by
secret-store(boltby default, orvaultwith thevault-*options). Use an external vault where your organisation runs one. - Edge credentials: tokens on devices in plants and remote sites are exposed to physical access. Store them with file permissions limited to the agent's service account, avoid passing them in URL query parameters on v1-compatible endpoints, and see the Secrets Management Guide and Device and IoT Identity Guide.
Logging and detection
InfluxDB writes structured server logs to standard output; set log-level (v2) or the InfluxDB 3 log options so request and authorisation errors are recorded, and ship them to your SIEM with the host journal. Combine them with network and platform signals.
| Signal | Source | Why it matters |
|---|---|---|
| Spikes in HTTP 401 and 403 responses | Server logs, reverse proxy logs | Invalid or revoked tokens in use, or token guessing |
| Token creation, deletion and operator token regeneration | Server logs, change records | New privileged credentials appearing outside a change |
| Writes from unexpected source addresses or to unexpected buckets | Proxy logs, flow logs, bucket cardinality | A token used from outside its site, or data injection into telemetry |
Recovery listener on 8182 or --without-auth in the service definition | Process and configuration monitoring | Authentication bypass left enabled |
| 8086 or 8181 reachable from the internet | External scans, cloud security group reviews | Direct exposure of the API |
In ATT&CK terms, watch for Valid Accounts (T1078) through stolen tokens, Unsecured Credentials (T1552) in agent configuration files and Exploit Public-Facing Application (T1190) against exposed endpoints. For OT environments, see the OT and ICS Identity and Access Guide for how machine credentials are governed across plant zones.
Metrics that show the controls work:
- InfluxDB endpoints reachable from the internet (target: zero).
- Share of tokens scoped to specific buckets or databases rather than operator, All Access or admin.
- Share of InfluxDB 3 named admin and resource tokens with an expiry set.
- Number of times the operator token was used outside break-glass in the period (target: zero).
- Percentage of client connections over TLS.
Hardening baseline
| Setting | Version | Recommended | Why |
|---|---|---|---|
http-bind-address | v2 (default :8086) | A private address and port | Accept connections only from collector and application networks |
--http-bind / INFLUXDB3_HTTP_BIND_ADDR | 3 (default 0.0.0.0:8181) | A private address | Same |
tls-cert, tls-key | v2 and 3 | Set | Encrypts tokens and telemetry in transit |
tls-min-version / tls-minimum-version | v2 (default 1.2) / 3 (default tls-1.2) | 1.2 or 1.3 | Refuse older protocol versions |
tls-strict-ciphers | v2 | On where clients support it | Limits to ECDHE with AES-GCM suites |
hardening-enabled | v2 | On | Private IP validation for Flux HTTP calls, templates and notification endpoints; from 2.10 also restricts health details |
health-auth-mode | v2.10+ | required | Hides /health and /ready details from callers without operator rights, while status codes still serve probes |
pprof-disabled, metrics-disabled, ui-disabled | v2 | Disable what you do not use | Reduces exposed profiling, metrics and UI endpoints |
strong-passwords, use-hashed-tokens | v2 | On (hashing is default from 2.9.0) | Password quality and token protection at rest |
--without-auth | 3 | Never in production | Removes token checks entirely |
--disable-authz | 3 | Only health or ping if a probe needs it | Keeps metrics and data behind tokens |
object-store-tls-allow-insecure | 3 | Off | Keeps certificate checks to object storage; the docs reserve it for testing |
Keep InfluxDB on a supported release and apply vendor security updates promptly. In OT networks, place the instance in a zone that collectors reach through defined conduits, and never route plant networks and the internet to the same listener.
Phased rollout
- Inventory: list instances, versions, bind addresses and every token with its owner and scope (
influx auth listin v2, the token listing in InfluxDB 3). - Close exposure: set the bind address and firewall rules first. This removes the largest risk with no client changes inside the trusted network.
- Re-scope tokens: create per-writer and per-dashboard tokens, roll clients one site at a time, watch 401 rates, then delete the broad tokens they replace.
- Contain the operator token: move it to a vault, create All Access or named admin tokens for operators and, on InfluxDB 3, regenerate
_adminonce everything uses named tokens. - Enable TLS and hardening: test
hardening-enabledon staging first, because private IP validation blocks Flux calls to internal addresses that some tasks rely on. Then roll to production. - Roll back: configuration options revert with a restart; keep previous values in version control. Plan v2 token hashing carefully, since the docs note that a later downgrade to 2.7 or earlier erases hashed tokens.
Framework mapping
| Control area | NIST SP 800-53 Rev 5 | NIST CSF 2.0 | CIS Controls v8.1 | ISO/IEC 27001:2022 |
|---|---|---|---|---|
| Bind address, firewall, disabled endpoints | SC-7, CM-7 | PR.PS-01 | 4 (Secure Configuration), 12 (Network Infrastructure) | A.8.20 Networks security |
| Token scoping and operator token containment | AC-6, IA-2 | PR.AA-05 | 5 (Account Management), 6 (Access Control Management) | A.8.2 Privileged access rights, A.5.15 Access control |
| Token storage, hashing, rotation, expiry | IA-5 | PR.AA-05 | 5, 6 | A.5.17 Authentication information |
| TLS | SC-8 | PR.DS-02 | 3 (Data Protection) | A.8.24 Use of cryptography |
| Logging and monitoring | AU-2 | DE.CM-01 | 8 (Audit Log Management) | A.8.15 Logging, A.8.16 Monitoring activities |
Common misconfigurations
- Keeping the default bind address on a routable host: the default listeners accept connections on all interfaces. Set a private bind address and confirm with a scan from outside the network.
- Operator token in agents and dashboards: the setup token is copied into Telegraf configurations or Grafana because it works everywhere. Replace it with scoped write and read tokens.
- One token shared across sites: a single write token deployed to every gateway cannot be revoked without stopping all collection. Issue one per site or device group.
- Running InfluxDB 3 with
--without-authafter testing: a test flag left in a container definition removes every token check. Alert on it in configuration reviews. - Tokens in URLs: v1-compatible
uandpquery parameters end up in proxy and access logs. Use theAuthorizationheader. - Upgrading to v2.9 without capturing the operator token: hashing makes the plaintext unrecoverable and complicates full restores. Store the operator token in a vault before the upgrade.
Practitioner checklist
- Set the bind address to a private interface and block 8086 and 8181 from the internet.
- Enable TLS with a minimum of TLS 1.2 on every instance.
- Store the operator token in a vault and use All Access or named admin tokens for administration.
- Issue one scoped write token per collector and separate read tokens for dashboards.
- Set expiry on InfluxDB 3 named admin and resource tokens and keep a rotation calendar for v2.
- Enable
hardening-enabled,strong-passwordsand token hashing on v2. - Never run production InfluxDB 3 with
--without-auth; use the recovery listener only on loopback during recovery. - Disable unused endpoints (
pprof,metrics, UI) and restrict health details. - Ship server and proxy logs to the SIEM and alert on 401 spikes and token changes.
Standards and references
- InfluxData: Manage API tokens (InfluxDB OSS v2)
- InfluxData: Enable security features (InfluxDB OSS v2)
- InfluxData: InfluxDB OSS v2 configuration options
- InfluxData: Enable TLS encryption (InfluxDB OSS v2)
- InfluxData: Manage admin tokens (InfluxDB 3 Core)
- InfluxData: InfluxDB 3 Core configuration options
- InfluxData: Manage resource tokens (InfluxDB 3 Enterprise)
- NIST: SP 800-53 Rev. 5, Security and Privacy Controls
Related NHI Mgmt Group resources: Database Security Guide · Secrets Management Guide · Database Credential and Access Security Guide · Privileged Access Management Guide