Manage API tokens

InfluxDB API tokens ensure secure interaction between InfluxDB and external tools such as clients or applications. An API token belongs to a specific user and identifies InfluxDB permissions within the user’s organization.

Learn how to create, view, update, or delete an API token.

API token types

• Operator API token
• All Access API token
• Read/Write token

Operator token

Grants full read and write access to all organizations and all organization resources in InfluxDB OSS 2.x. Some operations–for example, retrieving the server configuration–require operator permissions.

Initial operator token

When you first initialize InfluxDB, the setup process creates an initial user, org, bucket, and an Operator token with full read/write access to all organizations. When running setup, you can either:

• Supply the token value yourself (influx setup --token flag or the setup API token field), or
• Let InfluxDB auto-generate it. InfluxDB stores the generated token in the active influx CLI config so the CLI can use it later.

Creating operator tokens after setup

To create an operator token manually with the InfluxDB UI, api/v2 API, or influx CLI after the setup process is completed, you must use an existing Operator token.

To create a new Operator token without using an existing one, see how to use the influxd recovery auth CLI.

All Access token

Grants full read and write access to all resources in an organization.

Read/Write token

Grants read access, write access, or both to specific buckets in an organization.

Token hashing

InfluxDB can store API tokens as hashes on disk. Hashed storage protects tokens at rest: a copy of the underlying database file doesn’t expose usable tokens.

How token hashing works

When influxd starts with token hashing enabled:

1. Existing unhashed tokens are migrated to hashed form.
2. After migration, the original token strings cannot be retrieved.
3. New tokens created while hashing is enabled are stored as hashes.

Hashed tokens continue to authenticate exactly like unhashed tokens — clients and integrations that already store their token in plaintext continue to work.

If you disable token hashing later, tokens that have already been hashed on disk remain hashed. New tokens created while hashing is disabled are stored unhashed.

Before upgrading to 2.9.0

Backup and restore

A backup taken from an instance with token hashing enabled does not contain a plaintext operator token. To restore that backup with influx restore --full, supply the operator token via the --operator-token <token> flag (influx-cli v2.8.0+). Without that flag, the CLI cannot authenticate post-restore requests.

Disable token hashing

To opt out of the default — for example, to preserve compatibility with a possible downgrade to InfluxDB 2.7 or earlier — start influxd with the use-hashed-tokens option set to false:

influxd --use-hashed-tokens=false

Or set the environment variable or configuration file equivalent:

export INFLUXD_USE_HASHED_TOKENS=false

use-hashed-tokens: false

Downgrade considerations

Downgrading to InfluxDB 2.7 or earlier after token hashing has run on a database erases all stored tokens as part of the schema downgrade. If you may need to downgrade, start influxd 2.9.0 with --use-hashed-tokens=false so that token hashing never runs on the database.

If token hashing is never enabled, downgrading from 2.9.0 to 2.8.x or 2.7.x is supported. Downgrading directly to a version earlier than 2.7 is not recommended.

Replace a lost token

Because hashing prevents recovery of the original token string, replace lost tokens by creating a new token. To replace a lost operator token without an existing one, use influxd recovery auth.