Merge pull request #5984 from influxdata/jts-enterprise-resource-tokens

Manage Enterprise resource tokens for databases and system info
pbarnett/add-influxdb3-explorer-info^2
Jason Stirnaman 2025-04-15 08:34:10 -05:00 committed by GitHub
commit fc9d2c76b3
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 537 additions and 14 deletions

View File

@ -0,0 +1,21 @@
---
title: Manage resource tokens
seotitle: Manage resource tokens in {{< product-name >}}
description: >
Manage resource tokens in your {{< product-name >}} instance.
Resource tokens grant read and write permissions resources, such as databases
and system information endpoints in your {{< product-name >}} instance.
Database resource tokens allow for actions like writing and querying data.
menu:
influxdb3_enterprise:
parent: Manage tokens
name: Resource tokens
weight: 101
influxdb3/enterprise/tags: [tokens]
---
{{< children depth="1" >}}
<!-- The content for this page is at
// SOURCE - content/shared/influxdb3-admin/tokens/database/_index.md
-->

View File

@ -0,0 +1,511 @@
---
title: Create a resource token
description: >
Use the [`influxdb3 create token --permission` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/)
or the [HTTP API](/influxdb3/enterprise/api/v3/)
to create tokens that grant access to resources such as databases and system information.
Database tokens allow for reading and writing data in your {{< product-name omit="Clustered" >}} instance.
System tokens allow for reading system information and metrics for your server.
menu:
influxdb3_enterprise:
parent: Resource tokens
weight: 201
list_code_example: |
##### CLI
```bash
influxdb3 create token --permission \
--token ADMIN_TOKEN \
--expiry 1y \
--name "Read-write on DATABASE1, DATABASE2" \
db:DATABASE1,DATABASE2:read,write
```
##### HTTP API
"http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ADMIN_TOKEN" \
--data '{
"token_name": "Read-write for DATABASE1, DATABASE2",
"permissions": [{
"resource_type": "db",
"resource_identifier": ["DATABASE1","DATABASE2"],
"actions": ["read","write"]
}],
"expiry_secs": 300000
}'
```
alt_links:
cloud-dedicated: /influxdb3/enterprise/admin/tokens/create-token/
cloud-serverless: /influxdb3/cloud-serverless/admin/tokens/create-token/
---
Use the [`influxdb3 create token --permission` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/)
or the [`/api/v3/configure/token` HTTP API endpoint](/influxdb3/enterprise/api/v3/)
to create tokens that grant access to resources such as databases and system information.
Database tokens allow for reading and writing data in your {{< product-name omit="Clustered" >}} instance.
System tokens allow for reading system information and metrics for your server.
After you
[create an _admin token_](/influxdb3/enterprise/admin/token/admin/create/), 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](https://curl.se/) to send an API request, but you can use any HTTP client._
> [!Note]
> #### 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
{{< tabs-wrapper >}}
{{% tabs %}}
[influxdb3](#)
[HTTP API](#)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXDB3 ----------------------------->
Use the [`influxdb3 create token` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/)
to create a database token with permissions for reading and writing data in
your {{% product-name %}} instance.
In your terminal, run the `influxdb3 create token` command and provide the following:
- `--permission` flag to create a token with permissions
- `--name` flag with a unique description of the token
- _Options_, for example:
- `--expiry` option with the token expiration time as a [duration](/influxdb3/enterprise/reference/glossary/#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:ACTIONS` format--for example:
- db:DATABASE1,DATABASE2:read,write
- `db:`: The `db` resource type, which specifies the token is for a database.
- `DATABASE1,DATABASE2`: The names of the databases to grant permissions to.
The resource names part supports the `*` wildcard, which grants read or write permissions to all databases.
- `read,write`: The permissions to grant to the token.
{{% code-placeholders "DATABASE1|DATABASE2|1y" %}}
```bash
influxdb3 create token \
--permission \
--expiry 1y \
--name "Read-write on DATABASE1, DATABASE2" \
"db:DATABASE1,DATABASE2:read,write"
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE1`{{% /code-placeholder-key %}}, {{% code-placeholder-key %}}`DATABASE2`{{% /code-placeholder-key %}}:
your {{% product-name %}} [database](/influxdb3/enterprise/admin/databases/)
- {{% code-placeholder-key %}}`1y`{{% /code-placeholder-key %}}:
the token expiration time as a
[duration](/influxdb3/enterprise/reference/glossary/#duration).
The output is the token string in plain text.
<!-------------------------------- END INFLUXDB3 ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN cURL ---------------------------------->
Send a request to the following {{% product-name %}} endpoint:
{{% api-endpoint endpoint="http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" method="post" %}}
Provide the following request headers:
- `Accept: application/json` to ensure the response body is JSON content
- `Content-Type: application/json` to indicate the request body is JSON content
- `Authorization: Bearer` and the [admin token](/influxdb3/enterprise/admin/tokens/admin/)
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 instance
- `resource_type`: the resource type for the token, which is always `db`
- `resource_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.
- `permissions`: an array of token permission actions (`"read"`, `"write"`) for the database
- `expiry_secs`: Specify the token expiration time in seconds.
The following example shows how to use the HTTP API to create a database token:
{{% code-placeholders "DATABASE1|DATABASE2|300000" %}}
```bash
curl \
"http://{{< influxdb/host >}}/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
}'
```
{{% /code-placeholders %}}
Replace the following in your request:
- {{% code-placeholder-key %}}`DATABASE1`{{% /code-placeholder-key %}}, {{% code-placeholder-key %}}`DATABASE2`{{% /code-placeholder-key %}}:
your {{% product-name %}} [database](/influxdb3/enterprise/admin/databases/)
- {{% code-placeholder-key %}}`300000`{{% /code-placeholder-key %}}:
the token expiration time in seconds.
The response body contains token details, including the `token` field with the
token string in plain text.
<!------------------------------- END cURL ------------------------------------>
{{% /tab-content %}}
{{< /tabs-wrapper >}}
### Examples
- [Create a token with read and write access to a database](#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-and-write-access-to-all-databases)
- [Create a token with read-only access to a database](#create-a-token-with-read-only-access-to-a-database)
- [Create a token with read-only access to multiple databases](#create-a-token-with-read-only-access-to-multiple-databases)
- [Create a token with mixed permissions to multiple databases](#create-a-token-with-mixed-permissions-to-multiple-databases)
- [Create a token that expires in seven days](#create-a-token-that-expires-in-seven-days)
In the examples below, replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{< product-name >}} [database](/influxdb3/enterprise/admin/databases/)
- {{% code-placeholder-key %}}`DATABASE2_NAME`{{% /code-placeholder-key %}}: your {{< product-name >}} [database](/influxdb3/enterprise/admin/databases/)
- {{% code-placeholder-key %}}`ADMIN TOKEN`{{% /code-placeholder-key %}}: the [admin token](/influxdb3/enterprise/admin/tokens/admin/) for your {{% product-name %}} instance
{{% code-placeholders "DATABASE_NAME|DATABASE2_NAME|ADMIN_TOKEN" %}}
#### Create a token with read and write access to a database
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[influxdb3](#)
[HTTP API](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
```bash
influxdb3 create token \
--permission \
--name "Read/write token for DATABASE_NAME" \
db:DATABASE_NAME:read,write
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```bash
curl \
"http://{{< influxdb/host >}}/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"]
}]
}'
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
#### Create a token with read and write access to all databases
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[influxdb3](#)
[HTTP API](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
```bash
influxdb3 create token \
--permission \
--name "Read/write token for all databases" \
db:*:read,write
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```bash
curl \
"http://{{< influxdb/host >}}/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"]
}]
}'
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
#### Create a token with read-only access to a database
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[influxdb3](#)
[HTTP API](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
```bash
influxdb3 create token \
--permission \
--name "Read-only token for DATABASE_NAME" \
db:DATABASE_NAME:read
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```bash
curl \
"http://{{< influxdb/host >}}/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"]
}]
}'
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
#### Create a token with read-only access to multiple databases
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[influxdb3](#)
[HTTP API](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
```bash
influxdb3 create token \
--permission \
--name "Read-only token for DATABASE_NAME and DATABASE2_NAME" \
db:DATABASE_NAME,DATABASE2_NAME:read
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```bash
curl \
"http://{{< influxdb/host >}}/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"]
}]
}'
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
#### Create a token that expires in seven days
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[influxdb3](#)
[HTTP API](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
```bash
influxdb3 create token \
--permission \
--expiry 7d \
--name "Read/write token for DATABASE_NAME with 7d expiration" \
db:DATABASE_NAME:read,write
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```bash
curl \
"http://{{< influxdb/host >}}/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
}'
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
{{% /code-placeholders %}}
## 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 `/health` HTTP API endpoint
- `metrics`: system metrics information from the `/metrics` HTTP API endpoint
- `ping`: system ping information from the `/ping` HTTP API endpoint
{{< tabs-wrapper >}}
{{% tabs %}}
[influxdb3](#)
[HTTP API](#)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXDB3 ----------------------------->
Use the [`influxdb3 create token` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/)
to create a system token with permissions for reading system information from
your {{% product-name %}} instance.
In your terminal, run the `influxdb3 create token` command and provide the following:
- `--permission` flag to create a token with permissions
- `--name` flag with a unique description of the token
- _Options_, for example:
- `--expiry` option with the token expiration time as a [duration](/influxdb3/enterprise/reference/glossary/#duration).
If an expiration isn't set, the token does not expire until revoked.
- Token permissions in the `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example:
- system:health:read
- `system:`: The `system` resource 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).
{{% code-placeholders "1y" %}}
```bash
influxdb3 create token \
--permission \
--expiry 1y \
--name "System health token" \
"system:health:read"
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`1y`{{% /code-placeholder-key %}}:
the token expiration time as a
[duration](/influxdb3/enterprise/reference/glossary/#duration).
The output is the token string in plain text.
<!-------------------------------- END INFLUXDB3 ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN cURL ---------------------------------->
Send a request to the following {{% product-name %}} endpoint:
{{% api-endpoint endpoint="http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" method="post" %}}
Provide the following request headers:
- `Accept: application/json` to ensure the response body is JSON content
- `Content-Type: application/json` to indicate the request body is JSON content
- `Authorization: Bearer` and the [admin token](/influxdb3/enterprise/admin/tokens/admin/)
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 instance
- `resource_type`: the resource type for the token, which is `system` for system tokens
- `resource_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.
- `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:
{{% code-placeholders "300000" %}}
```bash
curl \
"http://{{< influxdb/host >}}/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
}'
```
{{% /code-placeholders %}}
Replace the following in your request:
- {{% code-placeholder-key %}}`300000`{{% /code-placeholder-key %}}:
the token expiration time in seconds.
The response body contains token details, including the `token` field with the
token string in plain text.
<!------------------------------- END cURL ------------------------------------>
{{% /tab-content %}}
{{< /tabs-wrapper >}}
## Output format
The `influxdb3 create token` command supports the `--format json` option.
By default, the command outputs the token string.
For [token details](/influxdb3/enterprise/api/management/#operation/CreateDatabaseToken) and 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.

View File

@ -1,11 +1,11 @@
---
title: List database tokens
title: List resource tokens
description: >
Use the `influxdb3 show tokens` command
to list database tokens in your InfluxDB 3 Enterprise instance.
to list resource tokens in your InfluxDB 3 Enterprise instance.
menu:
influxdb3_enterprise:
parent: Database tokens
parent: Resource tokens
weight: 202
list_code_example: |
##### CLI
@ -14,23 +14,14 @@ list_code_example: |
--token ADMIN_TOKEN
--host http://{{< influxdb/host >}}
```
##### API
```bash
curl \
--location "http://{{< influxdb/host >}}/api/v3/configure/tokens" \
--header "Accept: application/json" \
--header "Authorization: Bearer ADMIN_TOKEN"
```
aliases:
- /influxdb3/enterprise/admin/tokens/list/
related:
- /influxdb3/enterprise/reference/cli/influxdb3/token/list/
- /influxdb3/enterprise/reference/api/
source: /shared/influxdb3-admin/tokens/database/list.md
source: /shared/influxdb3-admin/tokens/admin/list.md
---
<!-- The content for this page is at
// file://content/shared/influxdb3-admin/tokens/database/list.md
// SOURCE content/shared/influxdb3-admin/tokens/admin/list.md
-->