Create a resource token
Use the influxdb3 create token --permission command
or the /api/v3/configure/token HTTP API endpoint
to create fine-grained permissions tokens that grant access to resources such as databases and system information.
Database tokens allow for reading and writing data in your InfluxDB 3 Enterprise instance.
System tokens allow for reading system information and metrics for your server.
After you
create an admin token, you
can use the token string to authenticate influxdb3 commands and HTTP API requests
for managing database and system tokens.
The HTTP API examples in this guide use cURL to send an API request, but you can use any HTTP client._
Store secure tokens in a secret store
Token strings are returned only on token creation. We recommend storing database tokens in a secure secret store. If you lose a resource token string, revoke the token and create a new one.
Create a database token
Use the influxdb3 create token command
to create a database token with fine-grained permissions for reading and writing data in
your InfluxDB 3 Enterprise instance.
In your terminal, run the influxdb3 create token --permission command and provide the following:
--name: A unique name for the tokenOptions, for example:
--expiry: The token expiration time as a duration. If an expiration isn’t set, the token does not expire until revoked.
Token permissions (read and write) in the
RESOURCE_TYPE:RESOURCE_NAMES:ACTIONSformat–for example:db:DATABASE1,DATABASE2:read,writedb:: Thedbresource type, which specifies the token is for a databaseDATABASE1,DATABASE2: A comma-separated list of database names to grant permissions to. The resource names part supports the*wildcard, which grants read or write permissions to all databases.read,write: A comma-separated list of permissions to grant to the token.
influxdb3 create token \
--permission \
--expiry 1y \
--name "Read-write on DATABASE1, DATABASE2" \
"db:DATABASE1,DATABASE2:read,write"
Replace the following:
DATABASE1,DATABASE2: your InfluxDB 3 Enterprise database1y: the token expiration time as a duration.
The output is the token string in plain text.
Send a request to the following InfluxDB 3 Enterprise endpoint:
Provide the following request headers:
Accept: application/jsonto ensure the response body is JSON contentContent-Type: application/jsonto indicate the request body is JSON contentAuthorization: Bearerand the admin token for your instance to authorize the request
In the request body, provide the following parameters:
token_name: a description of the token, unique within the instanceresource_type: the resource type for the token, which is alwaysdbresource_identifier: an array of database names to grant permissions to- The resource identifier field supports the
*wildcard, which grants read or write permissions to all databases.
- The resource identifier field supports the
permissions: an array of token permission actions ("read","write") for the databaseexpiry_secs: Specify the token expiration time in seconds.
The following example shows how to use the HTTP API to create a database token:
curl \
"http://localhost:8181/api/v3/enterprise/configure/token" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"token_name": "Read-write for DATABASE1, DATABASE2",
"permissions": [{
"resource_type": "db",
"resource_identifier": ["DATABASE1","DATABASE2"],
"actions": ["read","write"]
}],
"expiry_secs": 300000
}'
Replace the following in your request:
DATABASE1,DATABASE2: your InfluxDB 3 Enterprise database300000: the token expiration time in seconds.
The response body contains token details, including the token field with the
token string in plain text.
Examples
- Create a token with read and write access to a database
- Create a token with read and write access to all databases
- Create a token with read-only access to a database
- Create a token with read-only access to multiple databases
- Create a token with mixed permissions to multiple databases
- Create a token that expires in seven days
In the examples below, replace the following:
DATABASE_NAME: your InfluxDB 3 Enterprise databaseDATABASE2_NAME: your InfluxDB 3 Enterprise databaseADMIN TOKEN: the admin token for your InfluxDB 3 Enterprise instance
Create a token with read and write access to a database
influxdb3 create token \
--permission \
--name "Read/write token for DATABASE_NAME" \
db:DATABASE_NAME:read,write
curl \
"http://localhost:8181/api/v3/enterprise/configure/token" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ADMIN_TOKEN" \
--data '{
"token_name": "Read/write token for DATABASE_NAME",
"permissions": [{
"resource_type": "db",
"resource_identifier": ["DATABASE_NAME"],
"actions": ["read","write"]
}]
}'
Create a token with read and write access to all databases
influxdb3 create token \
--permission \
--name "Read/write token for all databases" \
db:*:read,write
curl \
"http://localhost:8181/api/v3/enterprise/configure/token" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ADMIN_TOKEN" \
--data '{
"token_name": "Read/write token for all databases",
"permissions": [{
"resource_type": "db",
"resource_identifier": ["*"],
"actions": ["read","write"]
}]
}'
Create a token with read-only access to a database
influxdb3 create token \
--permission \
--name "Read-only token for DATABASE_NAME" \
db:DATABASE_NAME:read
curl \
"http://localhost:8181/api/v3/enterprise/configure/token" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ADMIN_TOKEN" \
--data '{
"token_name": "Read-only token for DATABASE_NAME",
"permissions": [{
"resource_type": "db",
"resource_identifier": ["DATABASE_NAME"],
"actions": ["read"]
}]
}'
Create a token with read-only access to multiple databases
influxdb3 create token \
--permission \
--name "Read-only token for DATABASE_NAME and DATABASE2_NAME" \
db:DATABASE_NAME,DATABASE2_NAME:read
curl \
"http://localhost:8181/api/v3/enterprise/configure/token" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ADMIN_TOKEN" \
--data '{
"token_name": "Read-only token for DATABASE_NAME and DATABASE2_NAME",
"permissions": [{
"resource_type": "db",
"resource_identifier": ["DATABASE_NAME","DATABASE2_NAME"],
"actions": ["read"]
}]
}'
Create a token that expires in seven days
influxdb3 create token \
--permission \
--expiry 7d \
--name "Read/write token for DATABASE_NAME with 7d expiration" \
db:DATABASE_NAME:read,write
curl \
"http://localhost:8181/api/v3/enterprise/configure/token" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ADMIN_TOKEN" \
--data '{
"token_name": "Read/write token for DATABASE_NAME with 7d expiration",
"permissions": [{
"resource_type": "db",
"resource_identifier": ["DATABASE_NAME"],
"actions": ["read","write"]
}],
"expiry_secs": 604800
}'
Create a system token
System tokens have the system resource type and allow for read-only access
to system information and metrics from your server.
You can create system tokens for the following system resources:
health: system health information from the/healthHTTP API endpointmetrics: system metrics information from the/metricsHTTP API endpointping: system ping information from the/pingHTTP API endpoint
Use the influxdb3 create token command
to create a system token with permissions for reading system information from
your InfluxDB 3 Enterprise instance.
In your terminal, run the influxdb3 create token --permission command and provide the following:
--name: A unique name for the tokenOptions, for example:
--expiry: The token expiration time as a duration. If an expiration isn’t set, the token does not expire until revoked.
Token permissions in the
RESOURCE_TYPE:RESOURCE_NAMES:ACTIONSformat–for example:system:health:readsystem:: Thesystemresource type, which specifies the token is for system information.health: The specific system resource to grant permissions to.read: The permission to grant to the token (system tokens are always read-only).
influxdb3 create token \
--permission \
--expiry 1y \
--name "System health token" \
"system:health:read"
Replace the following:
1y: the token expiration time as a duration.
The output is the token string in plain text.
Send a request to the following InfluxDB 3 Enterprise endpoint:
Provide the following request headers:
Accept: application/jsonto ensure the response body is JSON contentContent-Type: application/jsonto indicate the request body is JSON contentAuthorization: Bearerand the admin token for your instance to authorize the request
In the request body, provide the following parameters:
token_name: a description of the token, unique within the instanceresource_type: the resource type for the token, which issystemfor system tokensresource_identifier: an array of system resource names to grant permissions to- The resource identifier field supports the
*wildcard, which grants read or write permissions to all system information resources.
- The resource identifier field supports the
permissions: an array of token permission actions (only"read"for system tokens)expiry_secs: Specify the token expiration time in seconds.
The following example shows how to use the HTTP API to create a system token:
curl \
"http://localhost:8181/api/v3/enterprise/configure/token" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ADMIN_TOKEN" \
--data '{
"token_name": "System health token",
"permissions": [{
"resource_type": "system",
"resource_identifier": ["health"],
"actions": ["read"]
}],
"expiry_secs": 300000
}'
Replace the following in your request:
300000: the token expiration time in seconds.
The response body contains token details, including the token field with the
token string in plain text.
Output format
The influxdb3 create token command supports the --format json option.
By default, the command outputs the token string.
For easier programmatic access to the command output, include --format json
with your command to format the output as JSON.
The /api/v3/configure/token endpoint outputs JSON format in the response body.
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB 3 Enterprise and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.