InfluxDB’s multi-tenancy model is designed to keep your data completely isolated, but it’s not about separate databases; it’s about separating users and their access.
Let’s see this in action. Imagine we have two distinct teams, "Marketing" and "Engineering," and we want them to have their own InfluxDB space without any overlap.
First, we need to create these separate spaces, which InfluxDB calls "Organizations."
influx org create \
--name Marketing \
--description "Marketing team's data"
influx org create \
--name Engineering \
--description "Engineering team's data"
You’ll get back output like this for each:
ID: abcdef0123456789
Name: Marketing
Status: active
Created At: 2023-10-27T10:00:00Z
Updated At: 2023-10-27T10:00:00Z
Description: Marketing team's data
Notice the ID. That’s the unique identifier for each organization. Now, how do these teams actually access their data? Through "Tokens." Tokens are the keys that grant specific permissions within a particular organization.
Let’s create a token for the Marketing team, giving them read and write access to all buckets within their organization.
influx auth create \
--org Marketing \
--description "Marketing API Token" \
--perms 'read:buckets,write:buckets'
Again, you’ll get something like this:
ID: fedcba9876543210
Token: <your_secret_token_here>
Org: Marketing
Description: Marketing API Token
Status: active
Created At: 2023-10-27T10:05:00Z
Updated At: 2023-10-27T10:05:00Z
Expires At: 2024-10-27T10:05:00Z
Permissions: read:buckets,write:buckets
Crucially, this token is the only time you’ll see the actual secret token string. Treat it like a password. If you lose it, you have to generate a new one.
Now, for the Engineering team:
influx auth create \
--org Engineering \
--description "Engineering Service Token" \
--perms 'read:buckets,write:buckets'
This will give you a different token, specific to the Engineering organization.
With these tokens, your applications or scripts can now interact with InfluxDB, but their actions will be confined to their respective organizations. For example, a marketing analytics tool would use the Marketing token, and it would never be able to see or write data to the Engineering organization, even if they share the same InfluxDB instance.
The mental model here is that an Organization is a logical container for data and users, providing a boundary. A Token is an access credential that operates within an organization and defines what actions can be performed. You don’t create separate InfluxDB instances for each tenant; you create separate organizations and manage access via tokens.
The read:buckets and write:buckets permissions are quite broad. You can get much more granular. For instance, if you wanted to allow a specific application to only write metrics to a particular bucket named performance_data within the Engineering organization, you’d use a more specific permission set like write:bucket:performance_data. This is how you achieve fine-grained control, ensuring that even within an organization, different applications or users have only the access they absolutely need.
When you set up your client libraries (like influxdb-client-go or influxdb-client-python), you’ll configure them with the Organization ID and the specific Token. For example, in Python:
from influxdb_client import InfluxDBClient, Point, WritePrecision
from influxdb_client.client.write_api import SYNCHRONOUS
# Marketing Client
marketing_client = InfluxDBClient(
url="http://localhost:8086",
token="<marketing_secret_token_here>", # Replace with actual token
org="Marketing"
)
marketing_write_api = marketing_client.write_api(write_options=SYNCHRONOUS)
# Engineering Client
engineering_client = InfluxDBClient(
url="http://localhost:8086",
token="<engineering_secret_token_here>", # Replace with actual token
org="Engineering"
)
engineering_write_api = engineering_client.write_api(write_options=SYNCHRONOUS)
# Now, any data written using marketing_write_api will go into the Marketing org.
# Any data written using engineering_write_api will go into the Engineering org.
# They are completely separate.
The underlying mechanism involves InfluxDB’s API Gateway. When a request comes in with a token, the gateway first validates the token and checks which organization it belongs to. All subsequent operations (like writing data, querying data, managing buckets) are then scoped to that organization. The data itself is stored in a way that physically separates data belonging to different organizations, even if they reside on the same storage backend.
The most common pitfall is confusing Organization IDs with Bucket IDs. While you can write data to a specific bucket within an organization, the primary isolation boundary is the organization itself, and tokens are scoped to that organization.
The next step is understanding how to manage users within these organizations and assign them roles for even more granular control.