Use a preconfigured admin token

Start InfluxDB 3 Enterprise with a preconfigured “offline” admin token file. If no admin tokens already exist, InfluxDB automatically creates an admin token using the provided admin token file. Offline tokens are designed to help with automated deployments.

• Generate an offline admin token file
  • Offline admin token file schema
• Start InfluxDB with the preconfigured admin token
• Use Docker Compose with preconfigured admin tokens
  • Create an admin token file
  • Configure Docker Compose with secrets
  • CI/CD setup

Generate an offline admin token file

Use the influxdb3 create token --admin command to generate an offline admin token file. Include the following options:

* Required

• --name: The name of the admin token (default is _admin) (replace TOKEN_NAME)
• --expiry: Duration for the token to remain valid, in humantime format (for example, 10d for 10 days or 1y for 1 year). (replace DURATION)
• * --offline
• * --output-file: File path to use for the generated token file (replace path/to/tokens.json)

influxdb3 create token --admin \
  --name 
TOKEN_NAME
 \
  --expiry 
DURATION
 \
  --offline \
  --output-file 
path/to/admin-token.json

Offline admin token file schema

An offline admin token file is a JSON-formatted file that contains a single object with the following fields:

• token: The raw token string (must begin with apiv3_)
• name: The token name (default is _admin)
• description: (Optional) A description of the token
• expiry_millis: (Optional) Token expiration time as a millisecond Unix timestamp

{
  "token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...",
  "name": "_admin",
  "description": "Admin token for InfluxDB 3",
  "expiry_millis": 1756400061529
}

Start InfluxDB with the preconfigured admin token

When starting InfluxDB 3 Enterprise, include the --admin-token-file option with the influxdb3 serve command or set the INFLUXDB3_ADMIN_TOKEN_FILE environment variable to provide the preconfigured offline admin token file:

influxdb3 serve \
  # ... \
  --admin-token-file 
path/to/admin-token.json

INFLUXDB3_ADMIN_TOKEN_FILE=
path/to/admin-token.json

influxdb3 serve \
  # ... \

When the server starts, you can use the preconfigured admin token to interact with your InfluxDB 3 Enterprise cluster or

instance.

Use Docker Compose with preconfigured admin tokens

For containerized deployments, you can use Docker Compose with Docker secrets to securely manage your preconfigured admin token.

Create an admin token file

Create a JSON file with your admin token using the offline admin token file schema:

{
  "token": "apiv3_your_token_here",
  "name": "admin",
  "description": "Admin token for automated deployment"
}

For security, restrict file permissions:

chmod 600 path/to/admin-token.json

Configure Docker Compose with secrets

Use Docker secrets to securely provide the admin token file to your container:

# compose.yaml
services:
  influxdb3-enterprise:
    image: influxdb:3-enterprise
    ports:
      - 8181:8181
    command:
      - influxdb3
      - serve
      - --node-id=node0
      - --cluster-id=cluster0
      - --object-store=file
      - --data-dir=/var/lib/influxdb3/data
      - --admin-token-file=/run/secrets/admin-token
    environment:
      - INFLUXDB3_ENTERPRISE_LICENSE_EMAIL=your-email@example.com
    secrets:
      - admin-token
    volumes:
      - type: bind
        source: ~/.influxdb3/data
        target: /var/lib/influxdb3/data

secrets:
  admin-token:
    file: path/to/admin-token.json

Start the service:

docker compose up -d

CI/CD setup

For CI/CD pipelines and automated environments, create the admin token file from environment variables:

# Create token file from CI/CD environment variable
echo "{\"token\": \"$INFLUXDB3_ADMIN_TOKEN\", \"name\": \"admin\", \"description\": \"CI/CD admin token\"}" > admin-token.json
chmod 600 admin-token.json

Then use the file in your Docker Compose configuration as shown above.