diff --git a/content/influxdb3/core/admin/tokens/_index.md b/content/influxdb3/core/admin/tokens/_index.md index 6ace87894..c4604b078 100644 --- a/content/influxdb3/core/admin/tokens/_index.md +++ b/content/influxdb3/core/admin/tokens/_index.md @@ -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 > \ No newline at end of file +--> \ No newline at end of file diff --git a/content/influxdb3/core/admin/tokens/admin/_index.md b/content/influxdb3/core/admin/tokens/admin/_index.md index ac5510003..f28deeeef 100644 --- a/content/influxdb3/core/admin/tokens/admin/_index.md +++ b/content/influxdb3/core/admin/tokens/admin/_index.md @@ -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 --- \ No newline at end of file diff --git a/content/influxdb3/core/admin/tokens/admin/create.md b/content/influxdb3/core/admin/tokens/admin/create.md index fe1abbe5e..714fbb16e 100644 --- a/content/influxdb3/core/admin/tokens/admin/create.md +++ b/content/influxdb3/core/admin/tokens/admin/create.md @@ -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: diff --git a/content/influxdb3/core/admin/tokens/admin/regenerate.md b/content/influxdb3/core/admin/tokens/admin/regenerate.md index fe7038826..c125ceda1 100644 --- a/content/influxdb3/core/admin/tokens/admin/regenerate.md +++ b/content/influxdb3/core/admin/tokens/admin/regenerate.md @@ -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 --- diff --git a/content/influxdb3/core/reference/cli/influxdb3/create/token.md b/content/influxdb3/core/reference/cli/influxdb3/create/token/_index.md similarity index 69% rename from content/influxdb3/core/reference/cli/influxdb3/create/token.md rename to content/influxdb3/core/reference/cli/influxdb3/create/token/_index.md index a27d89942..e73d9850c 100644 --- a/content/influxdb3/core/reference/cli/influxdb3/create/token.md +++ b/content/influxdb3/core/reference/cli/influxdb3/create/token/_index.md @@ -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 --- \ No newline at end of file diff --git a/content/influxdb3/core/reference/cli/influxdb3/create/token/admin.md b/content/influxdb3/core/reference/cli/influxdb3/create/token/admin.md new file mode 100644 index 000000000..6e72540a0 --- /dev/null +++ b/content/influxdb3/core/reference/cli/influxdb3/create/token/admin.md @@ -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 +--- + + \ No newline at end of file diff --git a/content/influxdb3/enterprise/admin/tokens/_index.md b/content/influxdb3/enterprise/admin/tokens/_index.md index 85bfad732..6c9a079ea 100644 --- a/content/influxdb3/enterprise/admin/tokens/_index.md +++ b/content/influxdb3/enterprise/admin/tokens/_index.md @@ -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 diff --git a/content/influxdb3/enterprise/admin/tokens/admin/create.md b/content/influxdb3/enterprise/admin/tokens/admin/create.md index 64530b6ef..9c821b4ab 100644 --- a/content/influxdb3/enterprise/admin/tokens/admin/create.md +++ b/content/influxdb3/enterprise/admin/tokens/admin/create.md @@ -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/ diff --git a/content/influxdb3/enterprise/admin/tokens/admin/regenerate.md b/content/influxdb3/enterprise/admin/tokens/admin/regenerate.md index f595ce3b5..ccf73ca14 100644 --- a/content/influxdb3/enterprise/admin/tokens/admin/regenerate.md +++ b/content/influxdb3/enterprise/admin/tokens/admin/regenerate.md @@ -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 --- diff --git a/content/influxdb3/enterprise/admin/tokens/resource/_index.md b/content/influxdb3/enterprise/admin/tokens/resource/_index.md index 2d66b6888..2e9aecb80 100644 --- a/content/influxdb3/enterprise/admin/tokens/resource/_index.md +++ b/content/influxdb3/enterprise/admin/tokens/resource/_index.md @@ -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" >}} diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token.md b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token.md deleted file mode 100644 index 968bbde4c..000000000 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token.md +++ /dev/null @@ -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 ---- - - diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/_index.md b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/_index.md index daffcce7d..1411c22bf 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/_index.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/_index.md @@ -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 --- \ No newline at end of file diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/admin.md b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/admin.md new file mode 100644 index 000000000..cf0f63ce6 --- /dev/null +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/admin.md @@ -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 +--- + + \ No newline at end of file diff --git a/content/shared/influxdb3-admin/distinct-value-cache/_index.md b/content/shared/influxdb3-admin/distinct-value-cache/_index.md index a21f2bd76..5f825c72d 100644 --- a/content/shared/influxdb3-admin/distinct-value-cache/_index.md +++ b/content/shared/influxdb3-admin/distinct-value-cache/_index.md @@ -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) diff --git a/content/shared/influxdb3-admin/distinct-value-cache/create.md b/content/shared/influxdb3-admin/distinct-value-cache/create.md index d0e4e69ea..c897c0dbf 100644 --- a/content/shared/influxdb3-admin/distinct-value-cache/create.md +++ b/content/shared/influxdb3-admin/distinct-value-cache/create.md @@ -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 diff --git a/content/shared/influxdb3-admin/last-value-cache/_index.md b/content/shared/influxdb3-admin/last-value-cache/_index.md index 5ced5aab5..0e17303e6 100644 --- a/content/shared/influxdb3-admin/last-value-cache/_index.md +++ b/content/shared/influxdb3-admin/last-value-cache/_index.md @@ -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) diff --git a/content/shared/influxdb3-admin/last-value-cache/create.md b/content/shared/influxdb3-admin/last-value-cache/create.md index 4a439ffc4..febc66f83 100644 --- a/content/shared/influxdb3-admin/last-value-cache/create.md +++ b/content/shared/influxdb3-admin/last-value-cache/create.md @@ -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 diff --git a/content/shared/influxdb3-admin/tokens/_index.md b/content/shared/influxdb3-admin/tokens/_index.md index 35f4da85a..d8d22a464 100644 --- a/content/shared/influxdb3-admin/tokens/_index.md +++ b/content/shared/influxdb3-admin/tokens/_index.md @@ -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 >}} diff --git a/content/shared/influxdb3-admin/tokens/admin/_index.md b/content/shared/influxdb3-admin/tokens/admin/_index.md index da3e84112..8a5c20ee7 100644 --- a/content/shared/influxdb3-admin/tokens/admin/_index.md +++ b/content/shared/influxdb3-admin/tokens/admin/_index.md @@ -1,2 +1,26 @@ - -{{< children hlevel="h2" readmore=true hr=true >}} \ No newline at end of file + +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 >}} diff --git a/content/shared/influxdb3-admin/tokens/admin/create.md b/content/shared/influxdb3-admin/tokens/admin/create.md index 093d5091a..d63014c26 100644 --- a/content/shared/influxdb3-admin/tokens/admin/create.md +++ b/content/shared/influxdb3-admin/tokens/admin/create.md @@ -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._ diff --git a/content/shared/influxdb3-admin/tokens/admin/list.md b/content/shared/influxdb3-admin/tokens/admin/list.md index 8bb72a3a4..ac2732cff 100644 --- a/content/shared/influxdb3-admin/tokens/admin/list.md +++ b/content/shared/influxdb3-admin/tokens/admin/list.md @@ -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 diff --git a/content/shared/influxdb3-admin/tokens/admin/regenerate.md b/content/shared/influxdb3-admin/tokens/admin/regenerate.md index d7c3f194e..76ac054c5 100644 --- a/content/shared/influxdb3-admin/tokens/admin/regenerate.md +++ b/content/shared/influxdb3-admin/tokens/admin/regenerate.md @@ -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 %}} 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. {{% /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. {{% /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. diff --git a/content/shared/influxdb3-cli/create/token.md b/content/shared/influxdb3-cli/create/token.md deleted file mode 100644 index ff49fee36..000000000 --- a/content/shared/influxdb3-cli/create/token.md +++ /dev/null @@ -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 - - - -```bash -influxdb3 create token -``` - -## 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 - - - -```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" %}} - - - -```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 -> ``` diff --git a/content/shared/influxdb3-cli/create/token/_index.md b/content/shared/influxdb3-cli/create/token/_index.md new file mode 100644 index 000000000..d1cb2139f --- /dev/null +++ b/content/shared/influxdb3-cli/create/token/_index.md @@ -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 + + + +```bash +influxdb3 create token +``` + +## 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 | + + diff --git a/content/shared/influxdb3-cli/create/token/admin.md b/content/shared/influxdb3-cli/create/token/admin.md new file mode 100644 index 000000000..bf938dadc --- /dev/null +++ b/content/shared/influxdb3-cli/create/token/admin.md @@ -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 of the token | +| `--expiry ` | Expires in `duration`, e.g 10d for 10 days 1y for 1 year | +| `--host ` | The host URL of the running InfluxDB 3 server [env: INFLUXDB3_HOST_URL=] [default: http://127.0.0.1:8181] | +| `--token ` | An existing admin token for the InfluxDB 3 server | +| `--tls-ca ` | An optional arg to use a custom ca for useful for testing with self signed certs | +| `--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 + + + +```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" %}} + + +```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" %}} + + + +```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 +> ``` diff --git a/content/shared/influxdb3-internals-reference/authentication.md b/content/shared/influxdb3-internals-reference/authentication.md index 843fc7c6b..491238dce 100644 --- a/content/shared/influxdb3-internals-reference/authentication.md +++ b/content/shared/influxdb3-internals-reference/authentication.md @@ -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. \ No newline at end of file + {{% 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 %}} \ No newline at end of file diff --git a/content/shared/v3-core-enterprise-release-notes/_index.md b/content/shared/v3-core-enterprise-release-notes/_index.md index 57fd2b854..ff46e3d03 100644 --- a/content/shared/v3-core-enterprise-release-notes/_index.md +++ b/content/shared/v3-core-enterprise-release-notes/_index.md @@ -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 diff --git a/content/shared/v3-core-get-started/_index.md b/content/shared/v3-core-get-started/_index.md index 7ebcfcd14..b9b6f9778 100644 --- a/content/shared/v3-core-get-started/_index.md +++ b/content/shared/v3-core-get-started/_index.md @@ -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 ` 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" >}}** | -| `influx` CLI | - | - | - | -| [`influxdb3` CLI](#influxdb3-cli){{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| `influxctl` CLI | - | - | - | -| [InfluxDB HTTP API](#influxdb-http-api){{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| InfluxDB user interface | - | - | - | +| `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/) | - | - | - | +| `influx` CLI | - | - | - | +| `influxctl` CLI | - | - | - | +| InfluxDB v2.x user interface | - | - | - | | **Third-party tools** | | | | | Flight SQL clients | - | - | **{{< icon "check" >}}** | | [Grafana](/influxdb3/version/visualize-data/grafana/) | - | - | **{{< icon "check" >}}** | diff --git a/content/shared/v3-enterprise-get-started/_index.md b/content/shared/v3-enterprise-get-started/_index.md index c200058a4..a106fe02f 100644 --- a/content/shared/v3-enterprise-get-started/_index.md +++ b/content/shared/v3-enterprise-get-started/_index.md @@ -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 ` 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" >}}** | -| `influx` CLI | - | - | - | -| [`influxdb3` CLI](#influxdb3-cli){{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| `influxctl` CLI | - | - | - | -| [InfluxDB HTTP API](#influxdb-http-api){{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| InfluxDB user interface | - | - | - | +| **`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/) | - | - | - | +| `influx` CLI | - | - | - | +| `influxctl` CLI | - | - | - | +| InfluxDB v2.x user interface | - | - | - | | **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/).