Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 39 ยท Concepts and Data Model

Buckets, Organizations and Tokens

Learn how InfluxDB organizes and protects data with organizations, buckets or databases, retention periods and least-privilege API tokens, with CLI examples.

Points need somewhere to live, and somebody has to decide who may read or write them. InfluxDB answers both questions with a small set of containers and credentials: organizations, buckets (2.x) or databases (1.x and 3.x), retention periods and API tokens.

This lesson explains each, shows how they differ between generations and gives a practical token plan so that a stolen collector credential cannot read your whole system.

The hierarchy

flowchart TB
  ORG["Organization (2.x)"] --> B1["Bucket: metrics<br/>retention 30 days"]
  ORG --> B2["Bucket: metrics_1h<br/>retention 1 year"]
  B1 --> M1["Measurements: cpu, mem, disk"]
  B2 --> M2["Measurements: cpu, mem, disk"]
  ORG --> T["API tokens with permissions per bucket"]

In 2.x the organization owns buckets and tokens; in 3.x the hierarchy is flatter: a server with databases that contain tables.

Organizations (2.x)

An organization is a workspace that groups users, buckets, dashboards, tasks and tokens. A small company usually has one. Cloud offerings use organizations to separate customers or teams. In InfluxDB 3 Core there is no organization layer: you address a database directly.

Buckets and databases

A bucket (2.x) is a named store of points with a retention period. All points in the bucket are subject to that period: data older than it is dropped automatically. InfluxDB 3 databases carry the same idea of a name and an optional retention period.

Terminal
# 2.x: create a bucket that keeps 30 days
influx bucket create --name metrics --retention 30d --org my-org

# 3.x: create a database with a retention period
influxdb3 create database metrics --retention-period 30d

Guidelines for designing buckets:

  • One bucket per retention need. Raw data for 7 days, hourly summaries for a year: two buckets. The retention chapter of this course builds on that.
  • Separate buckets for separate trust levels: public demo data apart from production, so tokens can be scoped.
  • Do not create a bucket per customer or per device unless you must: buckets have overhead and cross-bucket queries are harder. Use a tag with limited values instead.
  • A retention of 0 (or "infinite") means forever; choose it deliberately.

Retention periods are enforced in the background

Data is not removed the second it expires. The server checks periodically and drops whole chunks (shards or Parquet partitions) once everything in them is older than the retention period. Therefore storage may exceed the nominal retention for a while, and a query may briefly still see just-expired points.

API tokens

Every request must carry a token. A token is a long random string that maps to a set of permissions. You send it in the Authorization header:

TEXT
Authorization: Token <your-token>        # 2.x (and accepted by 3.x)
Authorization: Bearer <your-token>       # 3.x

There are different kinds:

Token kind Scope Use for
Operator / admin Everything Initial setup, administration; keep offline
All-access One organization Administrators of an org
Custom Specific buckets, read and/or write Collectors, apps, dashboards
Terminal
# 2.x: a write-only token for one bucket
influx auth create --org my-org --write-bucket "$(influx bucket list --name metrics --hide-headers | cut -f1)" \
  --description "telegraf on web-01"

# 3.x: scoped tokens depend on the edition; admin token creation is shown here
influxdb3 create token --admin

Exact options for scoped tokens in 3.x differ between Core, Enterprise and Cloud, so check influxdb3 create token --help for yours.

A least-privilege plan

  1. Collectors (Telegraf, agents): a write-only token for the one bucket they feed.
  2. Dashboards: a read-only token for the buckets they display.
  3. Administration: personal accounts or an all-access token used rarely.
  4. One token per consumer, with a description, so revoking one never breaks others.
  5. Rotate tokens on a schedule and immediately after a suspected leak.
  6. Never put a write token in a browser app or a public repository.

Stand-in: a tiny permission checker

The next block models tokens as lists of (bucket, action) permissions and checks requests against them. It is not how InfluxDB is implemented, but it demonstrates why scoped tokens limit damage.

JS Scoped tokens limit the blast radius (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: retention as a query

Retention simply means "delete rows older than N". With SQLite you can see the logic (a real server does it by dropping whole chunks and not row by row).

SQL What a 7-day retention keeps (SQLite stand-in)

Press Run (or Ctrl + Enter) to see the result here.

The cutoff is formatted exactly like the stored text, so plain string comparison orders correctly. Real tables should store consistent ISO 8601 strings or integer epochs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a bucket in InfluxDB 2.x combine?

    A bucket is a named container for points that enforces a retention period.
  2. 2. A Telegraf agent only needs to send metrics. Which token fits best?

    Least privilege: a leaked write-only token cannot read your data.
  3. 3. Why use separate buckets for raw data and hourly summaries?

    Raw data is kept briefly and summaries long, and retention applies per bucket.
  4. 4. Is expired data removed at the exact moment it passes the retention period?

    Enforcement is periodic and chunk based, so expired data can linger briefly.

Summary

  • 2.x organizes data as organization, bucket, measurement; 3.x as database and table.
  • A bucket or database carries a retention period that a background process enforces.
  • Tokens grant permissions; give each consumer its own narrow, described token and keep admin tokens out of applications.
  • Design buckets around retention and trust, not around every device or customer.

Next: Line Protocol