Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

feat(mono): 3.1 admin tokens: 

- Updates get-started and admin guides, CLI references
- Adds admin token CLI reference page
- Operator token (_admin) - system-generated, non-expiring
- Named admin tokens - user-defined with expiration support
- Resource tokens (Enterprise only) - database and system tokens
- Core vs Enterprise token limits properly documented
- Create the initial operator token
pull/6100/head
Jason Stirnaman 2025-05-28 13:48:56 -05:00
parent 7c989a0370
commit 2318cf7ac7
29 changed files with 453 additions and 390 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
content/influxdb3/core/admin/tokens/_index.md
View File

@ -1,7 +1,7 @@
---
title: Manage tokens
description: >
Manage tokens to authenticate and authorize access to resources and data in an {{< product-name >}} instance.
Manage tokens to authenticate and authorize access to server actions, resources, and data in an {{< product-name >}} instance.
menu:
influxdb3_core:
parent: Administer InfluxDB
@ -11,4 +11,4 @@ source: /shared/influxdb3-admin/tokens/_index.md
<!-- The content for this page is at
// SOURCE content/shared/influxdb3-admin/tokens/_index.md
-->>
-->

4
content/influxdb3/core/admin/tokens/admin/_index.md
View File

@ -11,9 +11,9 @@ menu:
name: Admin tokens
weight: 101
influxdb3/core/tags: [tokens]
source: /shared/influxdb3-admin/tokens/_index.md
source: /shared/influxdb3-admin/tokens/admin.md
---
<!-- The content for this page is at
// SOURCE content/shared/influxdb3-admin/tokens/_index.md
// SOURCE content/shared/influxdb3-admin/tokens/admin.md
-->

2
content/influxdb3/core/admin/tokens/admin/create.md
View File

@ -2,7 +2,7 @@
title: Create an admin token
description: >
Use the [`influxdb3 create token --admin` command](/influxdb3/core/reference/cli/influxdb3/create/token/)
or the [HTTP API](/influxdb3/core/api/v3/)
or the HTTP API [`/api/v3/configure/token/admin`](influxdb3/core/api/v3/#operation/PostCreateAdminToken) endpoint
to create an [admin token](/influxdb3/core/admin/tokens/admin/) for your {{< product-name omit="Clustered" >}} instance.
An admin token grants access to all actions on the server.
menu:

13
content/influxdb3/core/admin/tokens/admin/regenerate.md
View File

@ -2,8 +2,8 @@
title: Regenerate an admin token
description: >
Use the [`influxdb3 create token --admin` command](/influxdb3/core/reference/cli/influxdb3/create/token/)
or the [HTTP API](/influxdb3/core/api/v3/)
to regenerate an [admin token](/influxdb3/core/admin/tokens/admin/) for your {{< product-name omit="Clustered" >}} instance.
or the HTTP API [`/api/v3/configure/token/admin/regenerate`](/influxdb3/core/api/v3/#operation/PostRegenerateAdminToken) endpoint
to regenerate an [operator token](/influxdb3/core/admin/tokens/admin/) for your {{< product-name omit="Clustered" >}} instance.
An admin token grants access to all actions on the server.
Regenerating an admin token deactivates the previous token.
menu:
@ -14,8 +14,15 @@ list_code_example: |
##### CLI
```bash
influxdb3 create token --admin \
--token ADMIN_TOKEN \
--regenerate
OPERATOR_TOKEN
```
#### HTTP API
```bash
curl -X POST "http://{{< influxdb/host >}}/api/v3/configure/token/admin/regenerate" \
--header 'Authorization Bearer OPERATOR_TOKEN' \
--header 'Accept: application/json'
--header 'Content-Type: application/json'
```
source: /shared/influxdb3-admin/tokens/admin/regenerate.md
---

4
content/influxdb3/core/reference/cli/influxdb3/create/token.md → content/influxdb3/core/reference/cli/influxdb3/create/token/_index.md
View File

@ -7,9 +7,9 @@ menu:
parent: influxdb3 create
name: influxdb3 create token
weight: 400
source: /shared/influxdb3-cli/create/token.md
source: /shared/influxdb3-cli/create/token/_index.md
---
<!-- The content for this page is at
// SOURCE content/shared/influxdb3-cli/create/token.md
// SOURCE content/shared/influxdb3-cli/create/token/_index.md
-->

16
content/influxdb3/core/reference/cli/influxdb3/create/token/admin.md Normal file
View File

@ -0,0 +1,16 @@
---
title: influxdb3 create token admin
description: >
The `influxdb3 create token --admin` command creates a new operator or named
admin authentication token.
menu:
influxdb3_core:
parent: influxdb3 create token
name: influxdb3 create token admin
weight: 400
source: /shared/influxdb3-cli/create/token/admin.md
---
<!-- The content for this page is at
// SOURCE content/shared/influxdb3-cli/create/token/admin.md
-->

2
content/influxdb3/enterprise/admin/tokens/_index.md
View File

@ -1,7 +1,7 @@
---
title: Manage tokens
description: >
Manage tokens to authenticate and authorize access to resources and data in an {{< product-name >}} instance.
Manage tokens to authenticate and authorize access to server actions, resources, and data in an {{< product-name >}} instance.
menu:
influxdb3_enterprise:
parent: Administer InfluxDB

12
content/influxdb3/enterprise/admin/tokens/admin/create.md
View File

@ -2,8 +2,8 @@
title: Create an admin token
description: >
Use the [`influxdb3 create token --admin` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/)
or the [HTTP API](/influxdb3/enterprise/api/v3/)
to create an [admin token](/influxdb3/enterprise/admin/tokens/admin/) for your {{< product-name omit="Clustered" >}} instance.
or the HTTP API [`/api/v3/configure/token/admin`](/influxdb3/enterprise/api/v3/#operation/PostCreateAdminToken)
endpoint to create an operator or named [admin token](/influxdb3/enterprise/admin/tokens/admin/) for your {{< product-name omit="Clustered" >}} instance.
An admin token grants access to all actions on the server.
menu:
influxdb3_enterprise:
@ -12,13 +12,15 @@ weight: 201
list_code_example: |
##### CLI
```bash
influxdb3 create token --admin
influxdb3 create token --admin --name TOKEN_NAME
```
#### HTTP API
```bash
curl -X POST "http://{{< influxdb/host >}}/api/v3/configure/token/admin" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
--header 'Authorization Bearer ADMIN_TOKEN' \
--json '{
"name": "TOKEN_NAME"
}'
```
alt_links:
cloud-dedicated: /influxdb3/cloud-dedicated/admin/tokens/create-token/

12
content/influxdb3/enterprise/admin/tokens/admin/regenerate.md
View File

@ -1,10 +1,10 @@
---
title: Regenerate an admin token
title: Regenerate an operator admin token
description: >
Use the [`influxdb3 create token --admin` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/)
or the [HTTP API](/influxdb3/enterprise/api/v3/)
to regenerate an [admin token](/influxdb3/enterprise/admin/tokens/admin/) for your {{< product-name omit="Clustered" >}} instance.
An admin token grants access to all actions on the server.
An operator token grants access to all actions on the server.
Regenerating an admin token deactivates the previous token.
menu:
influxdb3_enterprise:
@ -14,9 +14,15 @@ list_code_example: |
##### CLI
```bash
influxdb3 create token --admin \
--token ADMIN_TOKEN \
--token OPERATOR_TOKEN \
--regenerate
```
#### HTTP API
```bash
curl -X POST "http://{{< influxdb/host >}}/api/v3/configure/token/admin/regenerate" \
--header 'Authorization Bearer OPERATOR_TOKEN'
```
source: /shared/influxdb3-admin/tokens/admin/regenerate.md
---

13
content/influxdb3/enterprise/admin/tokens/resource/_index.md
View File

@ -3,7 +3,7 @@ title: Manage resource tokens
seotitle: Manage resource tokens in {{< product-name >}}
description: >
Manage resource tokens in your {{< product-name >}} instance.
Resource tokens grant fine-grained permissions on resources, such as databases
Resource tokens grant permissions on specific 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:
@ -15,13 +15,12 @@ influxdb3/enterprise/tags: [tokens]
---
Manage resource tokens in your {{< product-name >}} instance.
Resource tokens grant fine-grained permissions on resources, such as databases
and system information endpoints in your {{< product-name >}} instance.
- **Databases**: Database tokens allow for actions like writing and querying data.
Resource tokens provide scoped access to specific resources:
- **System resources**: System information tokens allow read access to server runtime statistics and health.
Access controls for system information API endpoints help prevent information leaks and attacks (such as DoS).
- **Database tokens**: provide access to specific databases for actions like writing and querying data
- **System tokens**: provide access to system-level resources, such as API endpoints for server runtime statistics and health.
Resource tokens are user-defined and available only in {{% product-name %}}.
{{< children depth="1" >}}

16
content/influxdb3/enterprise/reference/cli/influxdb3/create/token.md
View File

@ -1,16 +0,0 @@
---
title: influxdb3 create token
description: >
The `influxdb3 create token` command creates a new authentication token.
menu:
influxdb3_enterprise:
parent: influxdb3 create
name: influxdb3 create token
weight: 400
source: /shared/influxdb3-cli/create/token.md
---
<!--
The content of this file is at
// SOURCE content/shared/influxdb3-cli/create/token.md
-->

9
content/influxdb3/enterprise/reference/cli/influxdb3/create/token/_index.md
View File

@ -1,19 +1,16 @@
---
title: influxdb3 create token
description: >
The `influxdb3 create token` command creates an admin token or a resource (fine-grained
permissions) token for authenticating and authorizing actions in an {{% product-name %}} instance.
The `influxdb3 create token` command creates an admin token or a scoped resource token for authenticating and authorizing actions in an {{% product-name %}} instance.
menu:
influxdb3_enterprise:
parent: influxdb3
name: influxdb3 create token
weight: 300
aliases:
- /influxdb3/enterprise/reference/cli/influxdb3/create/token/admin/
source: /shared/influxdb3-cli/create/token.md
source: /shared/influxdb3-cli/create/token/_index.md
---
<!--
The content of this page is at
// SOURCE content/shared/influxdb3-cli/create/token.md
// SOURCE content/shared/influxdb3-cli/create/token/_index.md
-->

16
content/influxdb3/enterprise/reference/cli/influxdb3/create/token/admin.md Normal file
View File

@ -0,0 +1,16 @@
---
title: influxdb3 create token admin
description: >
The `influxdb3 create token --admin` command creates a new operator or named
admin authentication token.
menu:
influxdb3_enterprise:
parent: influxdb3 create token
name: influxdb3 create token admin
weight: 400
source: /shared/influxdb3-cli/create/token/admin.md
---
<!-- The content for this page is at
// SOURCE content/shared/influxdb3-cli/create/token/admin.md
-->

3
content/shared/influxdb3-admin/distinct-value-cache/_index.md
View File

@ -4,10 +4,11 @@ values of one or more columns in a table, improving the performance of
queries that return distinct tag and field values.
The DVC is an in-memory cache that stores distinct values for specific columns
in a table. When you create an DVC, you can specify what columns' distinct
in a table. When you create a DVC, you can specify what columns' distinct
values to cache, the maximum number of distinct value combinations to cache, and
the maximum age of cached values. A DVC is associated with a table, which can
have multiple DVCs.
Caches import historical data when first created and reload data on restart.
{{< children type="anchored-list" >}}
- [Important things to know about the Distinct Value Cache](#important-things-to-know-about-the-distinct-value-cache)

10
content/shared/influxdb3-admin/distinct-value-cache/create.md
View File

@ -95,12 +95,10 @@ Replace the following:
- {{% code-placeholder-key %}}`DVC_NAME`{{% /code-placeholder-key %}}:
a unique name for the DVC
> [!Note]
> #### Values are cached on write
>
> Values are cached on write. When you create a cache, it will not cache
> previously written points, only newly written points.
>
The cache imports the distinct values from the table and starts caching them.
> [!Important]
> #### DVC size and persistence
>
> The DVC is stored in memory, so it's important to consider the size and

2
content/shared/influxdb3-admin/last-value-cache/_index.md
View File

@ -10,6 +10,8 @@ what fields to cache, what tags to use to identify each series, and the
number of values to cache for each unique series.
An LVC is associated with a table, which can have multiple LVCs.
Caches import historical data when first created and reload data on restart.
{{< children type="anchored-list" >}}
- [Important things to know about the Last Value Cache](#important-things-to-know-about-the-last-value-cache)
- [High cardinality key columns](#high-cardinality-key-columns)

9
content/shared/influxdb3-admin/last-value-cache/create.md
View File

@ -109,12 +109,9 @@ Replace the following:
- {{% code-placeholder-key %}}`LVC_NAME`{{% /code-placeholder-key %}}:
a unique name for the LVC
> [!Note]
> #### Values are cached on write
>
> Values are cached on write. When you create a cache, it will not cache
> previously written points, only newly written points.
>
The cache imports the distinct values from the table and starts caching them.
> [!Important]
> #### LVC size and persistence
>
> The LVC is stored in memory, so it's important to consider the size and persistence

43
content/shared/influxdb3-admin/tokens/_index.md
View File

@ -1,66 +1,65 @@
Manage tokens to authenticate and authorize access to resources and data in your {{< product-name >}} instance.
Manage tokens to authenticate and authorize access to server actions, resources, and data in your {{< product-name >}} instance.
## Provide your token
Before running CLI commands or making HTTP API requests, you must provide a valid token to authenticate.
If you start the {{< product-name >}} server with authentication enabled (the default), future server actions (CLI commands and HTTP API requests) require a valid token for authorization.
The first admin token you create is the _operator_ token (named `_admin`), which has full administrative privileges.
You can use the operator token to authenticate your requests and manage additional authorization tokens.
The mechanism for providing your token depends on the client you use to interact with {{% product-name %}}--for example:
{{< tabs-wrapper >}}
{{% tabs %}}
[influxdb3 CLI](#influxdb3-cli-auth)
[cURL](#curl-auth)
{{% /tabs %}}
{{% tab-content %}}
When using the `influxdb3` CLI, you can use the `--token` option to provide your authorization token.
{{% code-placeholders "YOUR_TOKEN" %}}
{{% code-placeholders "YOUR_AUTH_TOKEN" %}}
```bash
# Include the --token option in your influxdb3 command
influxdb3 query \
--token YOUR_TOKEN \
--database example-db \
"SELECT * FROM 'example-table' WHERE time > now() - INTERVAL '10 minutes'"
--token YOUR_AUTH_TOKEN \
--database DATABASE_NAME \
"SELECT * FROM 'DATABASE_NAME' WHERE time > now() - INTERVAL '10 minutes'"
```
{{% /code-placeholders %}}
You can also set the `INFLUXDB3_AUTH_TOKEN` environment variable to automatically provide your
authorization token to all `influxdb3` commands.
{{% code-placeholders "YOUR_TOKEN" %}}
{{% code-placeholders "YOUR_AUTH_TOKEN" %}}
```bash
# Export your token as an environment variable
export INFLUXDB3_AUTH_TOKEN=YOUR_TOKEN
export INFLUXDB3_AUTH_TOKEN=YOUR_AUTH_TOKEN
# Run an influxdb3 command without the --token option
influxdb3 query \
--database example-db \
"SELECT * FROM 'example-table' WHERE time > now() - INTERVAL '10 minutes'"
--database DATABASE_NAME \
"SELECT * FROM 'DATABASE_NAME' WHERE time > now() - INTERVAL '10 minutes'"
```
{{% /code-placeholders %}}
Replace `YOUR_TOKEN` with your authorization token.
{{% /tab-content %}}
{{% tab-content %}}
{{% code-placeholders "AUTH_TOKEN" %}}
{{% code-placeholders "YOUR_AUTH_TOKEN" %}}
```bash
# Add your token to the HTTP Authorization header
curl "http://{{< influxdb/host >}}/api/v3/query_sql" \
--header "Authorization: Bearer AUTH_TOKEN" \
--data-urlencode "db=example-db" \
--data-urlencode "q=SELECT * FROM 'example-table' WHERE time > now() - INTERVAL '10 minutes'"
--header "Authorization: Bearer YOUR_AUTH_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM 'DATABASE_NAME' WHERE time > now() - INTERVAL '10 minutes'"
```
{{% /code-placeholders %}}
Replace `AUTH_TOKEN` with your actual InfluxDB 3 token.
{{% /tab-content %}}
{{< /tabs-wrapper >}}
Replace the following with your values:
- {{% code-placeholder-key %}}`YOUR_AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link %}}
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database you want to query
{{< children hlevel="h2" readmore=true hr=true >}}

28
content/shared/influxdb3-admin/tokens/admin/_index.md
View File

@ -1,2 +1,26 @@
<!-->
{{< children hlevel="h2" readmore=true hr=true >}}
<!-- -->
Manage {{< product-name omit="Clustered" >}} admin tokens to authorize server actions, `influxdb3` CLI commands, and HTTP API endpoints for your {{< product-name omit="Clustered" >}} instance.
Administrative (_admin_) tokens provide full system access and management capabilities for your {{< product-name omit="Clustered" >}} instance.
{{% show-in "core" %}}
Admin tokens can create, edit, and delete other admin tokens.
{{% /show-in %}}
{{% show-in "enterprise" %}}
Admin tokens can create, edit, and delete other admin tokens, as well as manage [resource tokens](/influxdb3/version/admin/tokens/resource/).
{{% /show-in %}}
{{% product-name omit="Clustered" %}} supports two types of admin tokens:
- **Operator token**: A system-generated administrative token with the name `_admin`.
- Cannot be edited or deleted
- Never expires
- Cannot be recreated if lost (future functionality)
- Can be regenerated using the CLI
- **Named admin token**: User-defined administrative tokens with full admin permissions.
- Can be created, edited, and deleted
- Support expiration dates
- Cannot modify or remove the operator token
An {{% product-name omit="Clustered" %}} instance can have one operator token and unlimited named admin tokens.
{{< children hlevel="h2" readmore=true hr=true >}}

94
content/shared/influxdb3-admin/tokens/admin/create.md
View File

@ -1,18 +1,36 @@
Use the [`influxdb3 create token --admin` subcommand](/influxdb3/version/reference/cli/influxdb3/create/token/)
or the [HTTP API](/influxdb3/version/api/v3/)
to create an [admin token](/influxdb3/version/admin/tokens/admin/) for your {{< product-name omit="Clustered" >}} instance.
An admin token grants full access to all actions for your InfluxDB 3 instance.
with the `--name` option or the HTTP API [`/api/v3/configure/token/admin`](/influxdb3/version/api/v3/) endpoint
to create an admin token for your {{< product-name omit="Clustered" >}} instance.
An admin token grants full access to all actions for your InfluxDB 3 instance and can be referenced by its name.
{{% product-name omit="Clustered" %}} supports two types of admin tokens:
- **Operator token**: A system-generated administrative token with the name `_admin`.
- Cannot be edited or deleted
- Never expires
- Cannot be recreated if lost (future functionality)
- Can be regenerated using the CLI
- **Named admin token**: User-defined administrative tokens with full admin permissions.
- Can be created, edited, and deleted
- Support expiration dates
- Cannot modify or remove the operator token
An {{% product-name omit="Clustered" %}} instance can have one operator token and unlimited named admin tokens.
[Create an operator token](#create-an-operator-token)
[Create a named admin token](#create-a-named-admin-token)
> [!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**.
> Anyone with access to the admin token has full control over your {{< product-name >}} instance.
> If you lose the admin token string, you must regenerate the token.
> Anyone with access to the named admin token has full control over your {{< product-name >}} instance.
> If you lose the named admin token string, you must regenerate the token.
## Create an admin token
## Create an operator token
The first admin token your create for your {{% product-name %}}
instance is the operator token.
{{< tabs-wrapper >}}
{{% tabs %}}
@ -20,27 +38,71 @@ An admin token grants full access to all actions for your InfluxDB 3 instance.
[HTTP API](#use-the-http-api)
{{% /tabs %}}
{{% tab-content %}}
Use the `influxdb3 create token --admin` command:
Use the `influxdb3 create token --admin` command without a token name:
```bash
influxdb3 create token --admin
```
The output contains the token string in plain text.
To use the token as the default for later commands, and to persist the token
across sessions, assign the token string to the `INFLUXDB3_AUTH_TOKEN` environment variable.
{{% /tab-content %}}
{{% tab-content %}}
Use the following endpoint to create an admin token:
Use the following endpoint to create an operator token:
{{% api-endpoint method="POST" endpoint="/api/v3/configure/token/admin" api-ref="/influxdb3/version/api/v3/#operation/PostCreateAdminToken" %}}
```bash
curl -X POST "http://{{< influxdb/host >}}/api/v3/configure/token/admin" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
```
{{% /tab-content %}}
{{< /tabs-wrapper >}}
The output contains the token string in plain text.
## Create a named admin token
{{< tabs-wrapper >}}
{{% tabs %}}
[CLI](#use-the-influxdb3-cli)
[HTTP API](#use-the-http-api)
{{% /tabs %}}
{{% tab-content %}}
Use the `influxdb3 create token --admin` command with a token name:
{{% code-placeholders "TOKEN_NAME|ADMIN_TOKEN" %}}
```bash
influxdb3 create token --admin --token ADMIN_TOKEN --name "TOKEN_NAME"
```
{{% /code-placeholders %}}
Replace the following with your values:
- {{% code-placeholder-key %}}`ADMIN_TOKEN`{{% /code-placeholder-key %}}: your existing operator or named admin token
- {{% code-placeholder-key %}}`TOKEN_NAME`{{% /code-placeholder-key %}}: the name you want to assign to the new admin token
The output contains the token string in plain text.
{{% /tab-content %}}
{{% tab-content %}}
Use the following endpoint to create a named admin token:
{{% api-endpoint method="POST" endpoint="/api/v3/configure/token/admin" api-ref="/influxdb3/version/api/v3/#operation/PostCreateAdminToken" %}}
```bash
curl -X POST "http://{{< influxdb/host >}}/api/v3/configure/token/admin" \
--header 'Authorization Bearer ADMIN_TOKEN' \
--json '{
"name": "TOKEN_NAME"
}'
```
Replace the following with your values:
- {{% code-placeholder-key %}}`ADMIN_TOKEN`{{% /code-placeholder-key %}}: your existing operator or named admin token
- {{% code-placeholder-key %}}`TOKEN_NAME`{{% /code-placeholder-key %}}: the name you want to assign to the new admin token
The response body contains the token string in plain text.
{{% /tab-content %}}
{{< /tabs-wrapper >}}
_To use the token as the default for later commands, and to persist the token
across sessions, assign the token string to the `INFLUXDB3_AUTH_TOKEN` environment variable._

3
content/shared/influxdb3-admin/tokens/admin/list.md
View File

@ -12,8 +12,7 @@ data and resources in your InfluxDB 3 instance.
> #### Required permissions
>
> Listing admin tokens requires a valid InfluxDB {{% token-link "admin" %}}{{% show-in "enterprise" %}} or a token with read access to the `_internal` system database{{% /show-in %}}.
> For more information about providing a token, see [provide your token](/influxdb3/version/admin/tokens/#provide-your-token).
> For more information, see how to [provide your token](/influxdb3/version/admin/tokens/#provide-your-token).
## List all tokens

62
content/shared/influxdb3-admin/tokens/admin/regenerate.md
View File

@ -1,54 +1,45 @@
Use the `influxdb3` CLI or the HTTP API to regenerate an admin token.
Use the `influxdb3` CLI or the HTTP API to regenerate the operator (`_admin`) token for your {{% product-name %}} instance.
Regenerate a token to rotate it as part of your security practices or if you suspect
the token has been compromised.
{{< show-in "enterprise" >}}
Regenerating an admin token deactivates the previous token,
Regenerating the operator token deactivates the previous token,
stores the SHA512 hash and metadata of the new token, and returns the new token string.
{{< /show-in >}}
{{< show-in "core" >}}
Regenerating the admin token deactivates the previous token, updates the `_admin` token
SHA512 hash and metadata, and returns the new token string.
{{< /show-in >}}
An admin token grants access to all actions on the server.
## Prerequisite
To regenerate a token, you need the current token string.
To regenerate an operator token, you need the current token string.
## Use the CLI or HTTP API to regenerate an admin token
## Use the CLI or HTTP API to regenerate the operator token
> [!Important]
> #### Securely store your token
>
> InfluxDB lets you view the token string only when you create the token.
> Store your token in a secure location, as you cannot retrieve it from the database later.
> InfluxDB 3 stores only the token's hash and metadata in the catalog.
> #### Regenerating the operator token
> Regenerating the operator token invalidates the previous token.
> Make sure to update any applications or scripts that use the operator token.
To regenerate the operator token, use the [`influxdb3 serve create token` command] with the `--admin` and `--regenerate` flags:
{{< tabs-wrapper >}}
{{% tabs %}}
[CLI](#cli-regenerate-admin-token)
[HTTP API](#http-api-regenerate-admin-token)
[CLI](#cli-regenerate)
[HTTP API](#http-api-regenerate)
{{% /tabs %}}
{{% tab-content %}}
<!---------------------------------BEGIN CLI----------------------------------->
Use the `--regenerate` flag with the
`influxdb3 create token --admin` subcommand--for example:
[`influxdb3 create token --admin`](/influxdb3/version/reference/cli/influxdb3/create/token/) subcommand--for example:
{{% code-placeholders "ADMIN_TOKEN" %}}
{{% code-placeholders "OPERATOR_TOKEN" %}}
```bash
influxdb3 create token --admin \
--token ADMIN_TOKEN \
--regenerate
OPERATOR_TOKEN
```
{{% /code-placeholders %}}
In your command,
replace {{% code-placeholder-key %}}`ADMIN_TOKEN`{{% /code-placeholder-key %}}
with the current token string.
replace {{% code-placeholder-key %}}`OPERATOR_TOKEN`{{% /code-placeholder-key %}}
with the current operator (`_admin`) token string.
The CLI asks for confirmation before regenerating the token.
The output contains the new token string and InfluxDB deactivates the previous token string.
<!----------------------------END CLI------------------------------------------>
{{% /tab-content %}}
@ -58,20 +49,31 @@ Use the following HTTP API endpoint:
{{% api-endpoint method="POST" endpoint="/api/v3/configure/token/admin/regenerate" api-ref="/influxdb3/version/api/v3/configure/token/admin/regenerate" %}}
In your request, send an `Authorization` header with your current admin token string
In your request, send an `Authorization` header with your current operator token string
--for example:
{{% code-placeholders "ADMIN_TOKEN" %}}
{{% code-placeholders "OPERATOR_TOKEN" %}}
```bash
curl -X POST "http://{{< influxdb/host >}}/api/v3/configure/token/admin/regenerate" \
--header "Authorization: Bearer ADMIN_TOKEN" \
--header "Authorization: Bearer OPERATOR_TOKEN" \
--header "Accept: application/json"
```
{{% /code-placeholders %}}
In your command, replace {{% code-placeholder-key %}}`ADMIN_TOKEN`{{% /code-placeholder-key %}} with the current token string.
In your command, replace {{% code-placeholder-key %}}`OPERATOR_TOKEN`{{% /code-placeholder-key %}} with the current token string.
The output contains the new token string and InfluxDB deactivates the previous token string.
The response body contains the new operator token string in plain text, and InfluxDB deactivates the previous token string.
<!------------------------END HTTP API ---------------------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
To use the token as the default for later commands, and to persist the token
across sessions, assign the token string to the `INFLUXDB3_AUTH_TOKEN` environment variable.
## Important considerations
- Regenerating the operator token invalidates the previous token.
- If you lose the operator token, there is no recovery mechanism.
- `--regenerate` only works for the operator token. You can't use the `--regenerate` flag with the `influxdb3 create token --admin` command to regenerate a named admin token.
- Ensure that you update any applications or scripts that use the operator token with the new token string.
- Always store your operator token securely and consider implementing proper secret management practices.

65
content/shared/influxdb3-cli/create/token.md
View File

@ -1,65 +0,0 @@
The `influxdb3 create token` command creates a new authentication token. This returns the raw token string. Use it to authenticate future CLI commands and API requests.
> [!Important]
> InfluxDB displays the raw token string only once. Be sure to copy and securely store it.
## Usage
<!--pytest.mark.skip-->
```bash
influxdb3 create token <SUBCOMMAND>
```
## Commands
| Command | Description |
| :----- | :----------- | :------------------------------ |
| `--admin` | Create an admin token for the {{< product-name >}} server. |
{{% show-in "enterprise" %}}| [`--permission`](/influxdb3/enterprise/reference/cli/influxdb3/create/token/permission/) | Create a resource token with fine-grained access permissions. |{{% /show-in %}}
## Options
| Option | | Description |
| :----- | :------- | :--------------------- |
| |`--admin`| Create an admin token |
| `-h` | `--help` | Print help information |
## Examples
### Create an admin token
<!--pytest.mark.skip-->
```bash
influxdb3 create token --admin
```
The output is the raw token string you can use to authenticate future CLI commands and API requests.
For CLI commands, use the `--token` option or the `INFLUXDB3_AUTH_TOKEN` environment variable to pass the token string.
### Use the token to create a database
{{% code-placeholders "YOUR_ADMIN_TOKEN|DATABASE_NAME" %}}
<!--pytest.mark.skip-->
```bash
influxdb3 create database \
--token ADMIN_TOKEN \
DATABASE_NAME
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`ADMIN_TOKEN`{{% /code-placeholder-key %}}: Your InfluxDB admin token
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: Name for your new database
> [!Note]
> Set the token as an environment variable to simplify repeated CLI commands:
>
> ```bash
> export INFLUXDB3_AUTH_TOKEN=YOUR_ADMIN_TOKEN
> ```

28
content/shared/influxdb3-cli/create/token/_index.md Normal file
View File

@ -0,0 +1,28 @@
The `influxdb3 create token` command creates a new authentication token. This returns the raw token string. Use it to authenticate future CLI commands and API requests.
> [!Important]
> InfluxDB displays the raw token string only once. Be sure to copy and securely store it.
## Usage
<!--pytest.mark.skip-->
```bash
influxdb3 create token <SUBCOMMAND>
```
## Commands
| Command | Description |
| :----- | :----------- | :------------------------------ |
| [`--admin`](/influxdb3/version/reference/cli/influxdb3/create/token/admin/) | Create an operator or named admin token for the {{< product-name >}} server. |
{{% show-in "enterprise" %}}| [`--permission`](/influxdb3/enterprise/reference/cli/influxdb3/create/token/permission/) | Create a resource token with fine-grained access permissions. |{{% /show-in %}}
## Options
| Option | | Description |
| :----- | :------- | :--------------------- |
| |`--admin`| Create an admin token |
| `-h` | `--help` | Print help information |

81
content/shared/influxdb3-cli/create/token/admin.md Normal file
View File

@ -0,0 +1,81 @@
Create a new operator or named admin token.
## Usage
```
influxdb3 create token --admin [OPTIONS]
```
## Options
| Option | Description |
|:-------|:------------|
| `--regenerate` | Regenerates the operator token. Requires `--token` and the current operator token |
| `--name <NAME>` | Name of the token |
| `--expiry <EXPIRY>` | Expires in `duration`, e.g 10d for 10 days 1y for 1 year |
| `--host <host>` | The host URL of the running InfluxDB 3 server [env: INFLUXDB3_HOST_URL=] [default: http://127.0.0.1:8181] |
| `--token <token>` | An existing admin token for the InfluxDB 3 server |
| `--tls-ca <tls-ca>` | An optional arg to use a custom ca for useful for testing with self signed certs |
| `--format <FORMAT>` | Output format for token, supports just json or text [possible values: json, text] |
| `-h`, `--help` | Print help information |
| `--help-all` | Print more detailed help information |
## Examples
### Create an operator token
<!--pytest.mark.skip-->
```bash
influxdb3 create token --admin
```
The output is the raw token string you can use to authenticate future CLI commands and API requests.
For CLI commands, use the `--token` option or the `INFLUXDB3_AUTH_TOKEN` environment variable to pass the token string.
### Use the operator token to create a named admin token
{{% code-placeholders "OPERATOR_TOKEN|TOKEN_NAME|EXPIRY" %}}
<!--pytest.mark.skip-->
```bash
influxdb3 create token \
--admin \
--token OPERATOR_TOKEN \
--name TOKEN_NAME \
--expiry DURATION
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`OPERATOR_TOKEN`{{% /code-placeholder-key %}}: Your operator token for the server
- {{% code-placeholder-key %}}`TOKEN_NAME`{{% /code-placeholder-key %}}: Name for your new admin token
- {{% code-placeholder-key %}}`DURATION`{{% /code-placeholder-key %}}: Duration for the token to remain valid, in [humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html) format (for example, `10d` for 10 days or `1y` for 1 year).
### Use the token to create a database
{{% code-placeholders "YOUR_ADMIN_TOKEN|DATABASE_NAME" %}}
<!--pytest.mark.skip-->
```bash
influxdb3 create database \
--token ADMIN_TOKEN \
DATABASE_NAME
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`ADMIN_TOKEN`{{% /code-placeholder-key %}}: Your InfluxDB admin token
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: Name for your new database
> [!Note]
> #### Use CLI environment variables
> Set the token as an environment variable to simplify repeated CLI commands:
>
> ```bash
> export INFLUXDB3_AUTH_TOKEN=ADMIN_TOKEN
> ```

9
content/shared/influxdb3-internals-reference/authentication.md
View File

@ -1,7 +1,7 @@
<!--
-->
{{% product-name %}} uses an Attribute-Based Access Control (ABAC) model to
manage permissions.
manage permissions and supports multiple token types for different authentication scenarios.
{{% show-in "enterprise" %}}
This model allows for fine-grained control over access to resources and actions
@ -39,5 +39,10 @@ The ABAC model includes the following components:
{{% /show-in %}}
- **Resource**: The objects that can be accessed or manipulated.
Resources have attributes such as identifier and name.
In {{% product-name %}}, resources include databases and system information endpoints.
Resources have attributes such as identifier and name.
{{% show-in "enterprise" %}}
- Database tokens provide access to specific databases for actions like writing and querying data.
- System tokens provide access to system-level resources, such as API endpoints for server runtime statistics and health.
Access controls for system information API endpoints help prevent information leaks and attacks (such as DoS).
{{% /show-in %}}

11
content/shared/v3-core-enterprise-release-notes/_index.md
View File

@ -39,9 +39,12 @@
- Tokens can now be granted `CREATE` permission for creating databases
#### Additional Updates
- Last Value caches populate on creation and reload on restart
- Distinct Value caches populate on creation and reload on restart
- Last value caches populate on creation and reload on restart
- Distinct value caches populate on creation and reload on restart
- Other performance improvements
- Replaces remaining "INFLUXDB_IOX" Dockerfile environment variables with the following:
- `ENV INFLUXDB3_OBJECT_STORE=file`
- `ENV INFLUXDB3_DB_DIR=/var/lib/influxdb3`
#### Fixes
- Improvements and fixes for license validations
@ -49,10 +52,6 @@
- UX improvements for error and onboarding messages
- Other general fixes and corrections
## v3.0.3 {date="2025-05-16"}
**Core**: revision 384c457ef5f0d5ca4981b22855e411d8cac2688e

91
content/shared/v3-core-get-started/_index.md
View File

@ -249,30 +249,15 @@ influxdb3 serve --help
### Authentication and authorization
After you have [started the server](#start-influxdb), you can create and manage tokens using the `influxdb3` CLI or the HTTP API.
{{% product-name %}} uses token-based authentication and authorization which is enabled by default when you start the server.
{{% product-name %}} uses token-based authentication and authorization, which is enabled by default when you start the server.
With authentication enabled, you must provide a token with `influxdb3` CLI commands and HTTP API requests.
An {{% product-name %}} instance can have one _admin token_, which grants access to all CLI actions and API endpoints.
When you create a token, InfluxDB 3 returns a token string in plain text
that you use to authenticate CLI commands and API requests.
#### Create an operator token
To have the `influxdb3` CLI use your admin token automatically, assign it to the
`INFLUXDB3_AUTH_TOKEN` environment variable.
> [!Important]
> #### Securely store your token
>
> InfluxDB lets you view the token string only when you create the token.
> Store your token in a secure location, as you cannot retrieve it from the database later.
> InfluxDB 3 stores only the token's hash and metadata in the catalog.
#### Create an admin token
To create an admin token, use the `influxdb3 create token --admin` subcommand--for example:
After you start the server, create your first admin token (the operator token):
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[CLI](#)
[Docker](#)
@ -280,8 +265,7 @@ To create an admin token, use the `influxdb3 create token --admin` subcommand--f
{{% code-tab-content %}}
```bash
influxdb3 create token --admin \
--host http://INFLUXDB_HOST
influxdb3 create token --admin
```
{{% /code-tab-content %}}
@ -297,58 +281,63 @@ docker exec -it CONTAINER_NAME influxdb3 create token --admin
Replace {{% code-placeholder-key %}}`CONTAINER_NAME`{{% /code-placeholder-key %}} with the name of your running Docker container.
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
The command returns a token string that you can use to authenticate CLI commands and API requests.
Store your token in a secure location, as you cannot retrieve it from the database later.
The command returns a token string for authenticating CLI commands and API requests.
For more information about tokens, see how to [Manage admin tokens](/influxdb3/version/admin/tokens/admin/).
> [!Important]
> **Store your token securely**
>
> InfluxDB displays the token string only when you create it.
> Store your token securely—you cannot retrieve it from the database later.
#### Use tokens to authorize CLI commands and API requests
#### Set your token for authentication
With authentication enabled (the default), {{% product-name %}} requires a
token for all `influxdb3` CLI commands and HTTP API requests.
In the following examples, replace {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}} with your {{% token-link "admin" %}} string.
Use one of the following methods to authenticate requests.
In your commands, replace {{% code-placeholder-key %}}`YOUR_AUTH_TOKEN`{{% /code-placeholder-key %}} with your token string (for example, the [operator token](#create-an-operator-token) from the previous step).
{{< tabs-wrapper >}}
{{% tabs %}}
[CLI](#cli-use-a-token)
[HTTP API](#api-use-a-token)
[Environment variable (recommended)](#)
[Command option](#)
{{% /tabs %}}
{{% tab-content %}}
For `influxdb3` to use your token automatically, assign it your
token to the `INFLUXDB3_AUTH_TOKEN` environment variable:
{{% code-placeholders "AUTH_TOKEN" %}}
Set the `INFLUXDB3_AUTH_TOKEN` environment variable to have the CLI use your token automatically:
{{% code-placeholders "YOUR_AUTH_TOKEN" %}}
```bash
# Set the environment variable for future CLI commands
export INFLUXDB3_AUTH_TOKEN=AUTH_TOKEN
export INFLUXDB3_AUTH_TOKEN=YOUR_AUTH_TOKEN
```
{{% /code-placeholders %}}
Or to authenticate a single `influxdb3` CLI command and override `$INFLUXDB3_AUTH_TOKEN`, include the `--token` option:
{{% /tab-content %}}
{{% tab-content %}}
{{% code-placeholders "AUTH_TOKEN" %}}
Include the `--token` option with CLI commands:
{{% code-placeholders "YOUR_AUTH_TOKEN" %}}
```bash
# Use the --token option for a single command
influxdb3 show databases --token AUTH_TOKEN
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% tab-content %}}
To authenticate HTTP API requests, include `Bearer <TOKEN>` in the `Authorization` header value:
{{< /tabs-wrapper >}}
For HTTP API requests, include your token in the `Authorization` header:
{{% code-placeholders "AUTH_TOKEN" %}}
```bash
# Include the token in the Authorization HTTP request header
curl "http://{{< influxdb/host >}}/api/v3/configure/database" \
--header "Authorization: Bearer AUTH_TOKEN"
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{< /tabs-wrapper >}}
#### Learn more about token management
- [Manage admin tokens](/influxdb3/version/admin/tokens/admin/) - Create, list, and delete admin tokens
- [Token types and permissions](/influxdb3/version/admin/tokens/) - Understanding operator and named admin tokens
### Data model
@ -366,17 +355,17 @@ This tutorial covers many of the recommended tools.
| Tool | Administration | Write | Query |
| :------------------------------------------------------------------------------------------------ | :----------------------: | :----------------------: | :----------------------: |
| [Chronograf](/chronograf/v1/) | - | - | **{{< icon "check" >}}** |
| <span style="opacity:.5;">`influx` CLI</span> | - | - | - |
| [`influxdb3` CLI](#influxdb3-cli){{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| <span style="opacity:.5;">`influxctl` CLI</span> | - | - | - |
| [InfluxDB HTTP API](#influxdb-http-api){{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| <span style="opacity:.5;">InfluxDB user interface</span> | - | - | - |
| `influxdb3` CLI{{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| InfluxDB HTTP API {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [InfluxDB v2 client libraries](/influxdb3/version/reference/client-libraries/v2/) | - | **{{< icon "check" >}}** | - |
| [InfluxDB v1 client libraries](/influxdb3/version/reference/client-libraries/v1/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [InfluxDB 3 Processing engine](#python-plugins-and-the-processing-engine){{< req text="\* " color="magenta" >}} | | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [Telegraf](/telegraf/v1/) | - | **{{< icon "check" >}}** | - |
| [Chronograf](/chronograf/v1/) | - | - | - |
| <span style="opacity:.5;">`influx` CLI</span> | - | - | - |
| <span style="opacity:.5;">`influxctl` CLI</span> | - | - | - |
| <span style="opacity:.5;">InfluxDB v2.x user interface</span> | - | - | - |
| **Third-party tools** | | | |
| Flight SQL clients | - | - | **{{< icon "check" >}}** |
| [Grafana](/influxdb3/version/visualize-data/grafana/) | - | - | **{{< icon "check" >}}** |

181
content/shared/v3-enterprise-get-started/_index.md
View File

@ -270,28 +270,25 @@ You can learn more on managing your InfluxDB 3 Enterprise license on the [Manage
### Authentication and authorization
After you have [started the server](#start-influxdb), you can create and manage tokens using the `influxdb3` CLI or the HTTP API.
{{% product-name %}} uses token-based authentication and authorization which is enabled by default when you start the server.
{{% product-name %}} uses token-based authentication and authorization, which is enabled by default when you start the server.
With authentication enabled, you must provide a token with `influxdb3` CLI commands and HTTP API requests.
{{% product-name %}} uses token-based authentication and authorization which is enabled by default when you start the server.
{{% show-in "enterprise" %}}
{{% product-name %}} supports the following types of tokens:
- **admin token**: Grants access to all CLI actions and API endpoints. A server can have one admin token.
- **resource tokens**: Fine-grained permissions tokens that grant read and write access to specific resources (databases and system information endpoints) on the server.
- **resource tokens**: Tokens that grant read and write access to specific resources (databases and system information endpoints) on the server.
- A database token grants access to write and query data in a
database
- A system token grants read access to system information endpoints and
metrics for the server
{{% /show-in %}}
InfluxDB 3 supports the `*` resource name wildcard to grant permissions to all
resources of a specific type.
You can create multiple resource tokens for different resources.
When you create a token, InfluxDB 3 returns a token string in plain text
that you use to authenticate CLI commands and API requests.
To have the `influxdb3` CLI use your admin token automatically, assign it to the
`INFLUXDB3_AUTH_TOKEN` environment variable.
For more information about tokens and authorization, see [Manage tokens](/influxdb3/version/admin/tokens/).
> [!Important]
> #### Securely store your token
@ -300,12 +297,11 @@ To have the `influxdb3` CLI use your admin token automatically, assign it to the
> Store your token in a secure location, as you cannot retrieve it from the database later.
> InfluxDB 3 stores only the token's hash and metadata in the catalog.
#### Create an admin token
#### Create an operator token
To create an admin token, use the `influxdb3 create token --admin` subcommand--for example:
After you start the server, create your first admin token (the operator token):
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[CLI](#)
[Docker](#)
@ -313,8 +309,7 @@ To create an admin token, use the `influxdb3 create token --admin` subcommand--f
{{% code-tab-content %}}
```bash
influxdb3 create token --admin \
--host http://INFLUXDB_HOST
influxdb3 create token --admin
```
{{% /code-tab-content %}}
@ -330,146 +325,64 @@ docker exec -it CONTAINER_NAME influxdb3 create token --admin
Replace {{% code-placeholder-key %}}`CONTAINER_NAME`{{% /code-placeholder-key %}} with the name of your running Docker container.
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
The command returns a token string that you can use to authenticate CLI commands and API requests.
Store your token in a secure location, as you cannot retrieve it from the database later.
The command returns a token string for authenticating CLI commands and API requests.
For more information about tokens, see how to [Manage admin tokens](/influxdb3/version/admin/tokens/admin/).
> [!Important]
> **Store your token securely**
>
> InfluxDB displays the token string only when you create it.
> Store your token securely—you cannot retrieve it from the database later.
After you have created an admin token, you can use it to create database tokens and system tokens.
#### Set your token for authentication
#### Create a database token
To create a database token, use the `influxdb3 create token` subcommand and pass the following:
- `--permission`: Create a token with fine-grained permissions
- `--name`: A unique name for 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` option with the admin token to use for authentication
- Token permissions as a string literal in the `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example:
- `"db:mydb:read,write"`
- `db:`: The `db` resource type, which specifies the token is for a database
- `mydb`: The name of the database to grant permissions to. This part supports the `*` wildcard, which grants permissions to all databases.
- `read,write`: A comma-separated list of permissions to grant to the token.
The following example shows how to create a database token that expires in 90 days and has read and write permissions for all databases on the server:
{{% code-placeholders "ADMIN_TOKEN" %}}
```bash
influxdb3 create token \
--permission \
--expiry 90d \
--token ADMIN_TOKEN \
--host http://{{< influxdb/host >}} \
--name "rw all databases" \
"db:*:read,write"
```
{{% /code-placeholders %}}
In your command, replace {{% code-placeholder-key %}} `ADMIN_TOKEN`{{% /code-placeholder-key %}} with the admin token you created earlier.
#### Create a system token
A _system token_ grants read access to system information and metrics for the server, including the following HTTP API endpoints:
- `/health`
- `/metrics`
- `/ping`
To create a system token, use the `influxdb3 create token` subcommand and pass the following:
- `--permission`: Create a token with fine-grained permissions
- `--name`: A unique name for 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` option with the admin token to use for authentication
- `--host` option with the server host
- Token permissions as a string literal in the `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example:
- `"system:health:read"` or `"system:*:read"`
- `system:`: The `system` resource type, which specifies the token is for a database.
- `health`: The list of system resources (endpoints) to grant permissions to.
This part supports the `*` wildcard, which grants permissions to all endpoints.
- `read`: The list of permissions to grant. _Only `read` is supported for system resources._
The following example shows how to create a system token that expires in 1 year and has read permissions for all system endpoints on the server:
{{% code-placeholders "ADMIN_TOKEN" %}}
```bash
influxdb3 create token \
--permission \
--expiry 1y \
--token ADMIN_TOKEN \
--host http://{{< influxdb/host >}} \
--name "all system endpoints" \
"system:*:read"
```
{{% /code-placeholders %}}
In your command, replace {{% code-placeholder-key %}} `ADMIN_TOKEN`{{% /code-placeholder-key %}} with the admin token you created earlier.
For more information, see how to [Manage resource tokens](/influxdb3/version/admin/tokens/resource/).
#### Use tokens to authorize CLI commands and API requests
#### Use tokens to authorize CLI commands and API requests
With authentication enabled (the default), {{% product-name %}} requires a
token for all `influxdb3` CLI commands and HTTP API requests.
In the following examples, replace {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}} with your {{% token-link "admin" %}} string.
Use one of the following methods to authenticate requests.
In your commands, replace {{% code-placeholder-key %}}`YOUR_AUTH_TOKEN`{{% /code-placeholder-key %}} with your token string (for example, the [operator token](#create-an-operator-token) from the previous step).
{{< tabs-wrapper >}}
{{% tabs %}}
[CLI](#cli-use-a-token)
[HTTP API](#api-use-a-token)
[Environment variable (recommended)](#)
[Command option](#)
{{% /tabs %}}
{{% tab-content %}}
For `influxdb3` to use your token automatically, assign it your
token to the `INFLUXDB3_AUTH_TOKEN` environment variable:
{{% code-placeholders "AUTH_TOKEN" %}}
Set the `INFLUXDB3_AUTH_TOKEN` environment variable to have the CLI use your token automatically:
{{% code-placeholders "YOUR_AUTH_TOKEN" %}}
```bash
# Set the environment variable for future CLI commands
export INFLUXDB3_AUTH_TOKEN=AUTH_TOKEN
export INFLUXDB3_AUTH_TOKEN=YOUR_AUTH_TOKEN
```
{{% /code-placeholders %}}
Or to authenticate a single `influxdb3` CLI command and override `$INFLUXDB3_AUTH_TOKEN`, include the `--token` option:
{{% /tab-content %}}
{{% tab-content %}}
{{% code-placeholders "AUTH_TOKEN" %}}
Include the `--token` option with CLI commands:
{{% code-placeholders "YOUR_AUTH_TOKEN" %}}
```bash
# Use the --token option for a single command
influxdb3 show databases --token AUTH_TOKEN
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% tab-content %}}
To authenticate HTTP API requests, include `Bearer <TOKEN>` in the `Authorization` header value:
{{< /tabs-wrapper >}}
For HTTP API requests, include your token in the `Authorization` header:
{{% code-placeholders "AUTH_TOKEN" %}}
```bash
# Include the token in the Authorization HTTP request header
curl "http://{{< influxdb/host >}}/api/v3/configure/database" \
--header "Authorization: Bearer AUTH_TOKEN"
```
{{% /code-placeholders %}}
{{% code-placeholders "SYSTEM_TOKEN" %}}
```bash
curl "http://{{< influxdb/host >}}/health" \
--header "Authorization: Bearer SYSTEM_TOKEN"
```
{{% /code-placeholders %}}
#### Learn more about token management
Replace {{% code-placeholder-key %}}`SYSTEM_TOKEN`{{% /code-placeholder-key %}} with the system token string that grants access to system endpoints (`/health`, `/metrics`)
{{% /tab-content %}}
{{< /tabs-wrapper >}}
- [Manage admin tokens](/influxdb3/version/admin/tokens/admin/) - Create, list, and delete admin tokens
- [Manage resource tokens](/influxdb3/version/admin/tokens/resource/) - Create, list, and delete resource tokens
- [Token types and permissions](/influxdb3/version/admin/tokens/) - Understanding operator and named admin tokens
### Data model
@ -487,17 +400,17 @@ This tutorial covers many of the recommended tools.
| Tool | Administration | Write | Query |
| :------------------------------------------------------------------------------------------------ | :----------------------: | :----------------------: | :----------------------: |
| [Chronograf](/chronograf/v1/) | - | - | **{{< icon "check" >}}** |
| <span style="opacity:.5;">`influx` CLI</span> | - | - | - |
| [`influxdb3` CLI](#influxdb3-cli){{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| <span style="opacity:.5;">`influxctl` CLI</span> | - | - | - |
| [InfluxDB HTTP API](#influxdb-http-api){{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| <span style="opacity:.5;">InfluxDB user interface</span> | - | - | - |
| **`influxdb3` CLI** {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| **InfluxDB HTTP API** {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [InfluxDB v2 client libraries](/influxdb3/version/reference/client-libraries/v2/) | - | **{{< icon "check" >}}** | - |
| [InfluxDB v1 client libraries](/influxdb3/version/reference/client-libraries/v1/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [InfluxDB 3 Processing engine](#python-plugins-and-the-processing-engine){{< req text="\* " color="magenta" >}} | | **{{< icon "check" >}}** | **{{< icon "check" >}}** |
| [Telegraf](/telegraf/v1/) | - | **{{< icon "check" >}}** | - |
| [Chronograf](/chronograf/v1/) | - | - | - |
| <span style="opacity:.5;">`influx` CLI</span> | - | - | - |
| <span style="opacity:.5;">`influxctl` CLI</span> | - | - | - |
| <span style="opacity:.5;">InfluxDB v2.x user interface</span> | - | - | - |
| **Third-party tools** | | | |
| Flight SQL clients | - | - | **{{< icon "check" >}}** |
| [Grafana](/influxdb3/version/visualize-data/grafana/) | - | - | **{{< icon "check" >}}** |
@ -986,6 +899,7 @@ visualization of your time series data.
### Last values cache
{{% product-name %}} supports a **last-n values cache** which stores the last N values in a series or column hierarchy in memory. This gives the database the ability to answer these kinds of queries in under 10 milliseconds.
Last value caches import historical data when first created, and reload data on restart to ensure cache consistency and eliminate cold start delays.
You can use the `influxdb3` CLI to [create a last value cache](/influxdb3/version/reference/cli/influxdb3/create/last_cache/).
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TABLE_NAME|CACHE_NAME" %}}
@ -1071,6 +985,7 @@ Replace the following placeholders with your values:
Similar to the [last values cache](#last-values-cache), the database can cache in RAM the distinct values for a single column in a table or a hierarchy of columns.
This is useful for fast metadata lookups, which can return in under 30 milliseconds.
Many of the options are similar to the last value cache.
Distinct values caches import historical data when first created, and reload data on restart to ensure cache consistency and eliminate cold start delays.
You can use the `influxdb3` CLI to [create a distinct values cache](/influxdb3/version/reference/cli/influxdb3/create/distinct_cache/).