diff --git a/content/influxdb3/enterprise/admin/tokens/resource/_index.md b/content/influxdb3/enterprise/admin/tokens/resource/_index.md new file mode 100644 index 000000000..025064604 --- /dev/null +++ b/content/influxdb3/enterprise/admin/tokens/resource/_index.md @@ -0,0 +1,21 @@ +--- +title: Manage resource tokens +seotitle: Manage resource tokens in {{< product-name >}} +description: > + Manage resource tokens in your {{< product-name >}} instance. + Resource tokens grant read and write permissions resources, such as databases + and system information endpoints in your {{< product-name >}} instance. + Database resource tokens allow for actions like writing and querying data. +menu: + influxdb3_enterprise: + parent: Manage tokens + name: Resource tokens +weight: 101 +influxdb3/enterprise/tags: [tokens] +--- + +{{< children depth="1" >}} + + diff --git a/content/influxdb3/enterprise/admin/tokens/resource/create.md b/content/influxdb3/enterprise/admin/tokens/resource/create.md new file mode 100644 index 000000000..ae252c2c2 --- /dev/null +++ b/content/influxdb3/enterprise/admin/tokens/resource/create.md @@ -0,0 +1,511 @@ +--- +title: Create a resource token +description: > + Use the [`influxdb3 create token --permission` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/) + or the [HTTP API](/influxdb3/enterprise/api/v3/) + to create tokens that grant access to resources such as databases and system information. + Database tokens allow for reading and writing data in your {{< product-name omit="Clustered" >}} instance. + System tokens allow for reading system information and metrics for your server. +menu: + influxdb3_enterprise: + parent: Resource tokens +weight: 201 +list_code_example: | + ##### CLI + ```bash + influxdb3 create token --permission \ + --token ADMIN_TOKEN \ + --expiry 1y \ + --name "Read-write on DATABASE1, DATABASE2" \ + db:DATABASE1,DATABASE2:read,write + ``` + + ##### HTTP API + "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header "Authorization: Bearer ADMIN_TOKEN" \ + --data '{ + "token_name": "Read-write for DATABASE1, DATABASE2", + "permissions": [{ + "resource_type": "db", + "resource_identifier": ["DATABASE1","DATABASE2"], + "actions": ["read","write"] + }], + "expiry_secs": 300000 + }' + ``` +alt_links: + cloud-dedicated: /influxdb3/enterprise/admin/tokens/create-token/ + cloud-serverless: /influxdb3/cloud-serverless/admin/tokens/create-token/ +--- + +Use the [`influxdb3 create token --permission` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/) +or the [`/api/v3/configure/token` HTTP API endpoint](/influxdb3/enterprise/api/v3/) +to create tokens that grant access to resources such as databases and system information. +Database tokens allow for reading and writing data in your {{< product-name omit="Clustered" >}} instance. +System tokens allow for reading system information and metrics for your server. + +After you +[create an _admin token_](/influxdb3/enterprise/admin/token/admin/create/), you +can use the token string to authenticate `influxdb3` commands and HTTP API requests +for managing database and system tokens. + +The HTTP API examples in this guide use [cURL](https://curl.se/) to send an API request, but you can use any HTTP client._ + +> [!Note] +> #### Store secure tokens in a secret store +> +> Token strings are returned _only_ on token creation. +> We recommend storing database tokens in a **secure secret store**. +> If you lose a resource token string, revoke the token and create a new one. + +## Create a database token + +{{< tabs-wrapper >}} +{{% tabs %}} +[influxdb3](#) +[HTTP API](#) +{{% /tabs %}} +{{% tab-content %}} + + + +Use the [`influxdb3 create token` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/) +to create a database token with permissions for reading and writing data in +your {{% product-name %}} instance. + +In your terminal, run the `influxdb3 create token` command and provide the following: + +- `--permission` flag to create a token with permissions +- `--name` flag with a unique description of the token +- _Options_, for example: + - `--expiry` option with the token expiration time as a [duration](/influxdb3/enterprise/reference/glossary/#duration). + If an expiration isn't set, the token does not expire until revoked. +- Token permissions (read and write) in the `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example: + - db:DATABASE1,DATABASE2:read,write + - `db:`: The `db` resource type, which specifies the token is for a database. + - `DATABASE1,DATABASE2`: The names of the databases to grant permissions to. + The resource names part supports the `*` wildcard, which grants read or write permissions to all databases. + - `read,write`: The permissions to grant to the token. + +{{% code-placeholders "DATABASE1|DATABASE2|1y" %}} + +```bash +influxdb3 create token \ +--permission \ +--expiry 1y \ +--name "Read-write on DATABASE1, DATABASE2" \ +"db:DATABASE1,DATABASE2:read,write" +``` + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE1`{{% /code-placeholder-key %}}, {{% code-placeholder-key %}}`DATABASE2`{{% /code-placeholder-key %}}: + your {{% product-name %}} [database](/influxdb3/enterprise/admin/databases/) +- {{% code-placeholder-key %}}`1y`{{% /code-placeholder-key %}}: + the token expiration time as a + [duration](/influxdb3/enterprise/reference/glossary/#duration). + +The output is the token string in plain text. + + +{{% /tab-content %}} +{{% tab-content %}} + + +Send a request to the following {{% product-name %}} endpoint: + +{{% api-endpoint endpoint="http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" method="post" %}} + +Provide the following request headers: + +- `Accept: application/json` to ensure the response body is JSON content +- `Content-Type: application/json` to indicate the request body is JSON content +- `Authorization: Bearer` and the [admin token](/influxdb3/enterprise/admin/tokens/admin/) + for your instance to authorize the request + +In the request body, provide the following parameters: + +- `token_name`: a description of the token, unique within the instance +- `resource_type`: the resource type for the token, which is always `db` +- `resource_identifier`: an array of database names to grant permissions to + - The resource identifier field supports the `*` wildcard, which grants read or write + permissions to all databases. +- `permissions`: an array of token permission actions (`"read"`, `"write"`) for the database +- `expiry_secs`: Specify the token expiration time in seconds. + +The following example shows how to use the HTTP API to create a database token: + +{{% code-placeholders "DATABASE1|DATABASE2|300000" %}} + +```bash + curl \ + "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --data '{ + "token_name": "Read-write for DATABASE1, DATABASE2", + "permissions": [{ + "resource_type": "db", + "resource_identifier": ["DATABASE1","DATABASE2"], + "actions": ["read","write"] + }], + "expiry_secs": 300000 + }' +``` + +{{% /code-placeholders %}} + +Replace the following in your request: + +- {{% code-placeholder-key %}}`DATABASE1`{{% /code-placeholder-key %}}, {{% code-placeholder-key %}}`DATABASE2`{{% /code-placeholder-key %}}: + your {{% product-name %}} [database](/influxdb3/enterprise/admin/databases/) +- {{% code-placeholder-key %}}`300000`{{% /code-placeholder-key %}}: + the token expiration time in seconds. + +The response body contains token details, including the `token` field with the +token string in plain text. + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +### Examples + +- [Create a token with read and write access to a database](#create-a-token-with-read-and-write-access-to-a-database) +- [Create a token with read and write access to all databases](#create-a-token-with-read-and-write-access-to-all-databases) +- [Create a token with read-only access to a database](#create-a-token-with-read-only-access-to-a-database) +- [Create a token with read-only access to multiple databases](#create-a-token-with-read-only-access-to-multiple-databases) +- [Create a token with mixed permissions to multiple databases](#create-a-token-with-mixed-permissions-to-multiple-databases) +- [Create a token that expires in seven days](#create-a-token-that-expires-in-seven-days) + +In the examples below, replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{< product-name >}} [database](/influxdb3/enterprise/admin/databases/) +- {{% code-placeholder-key %}}`DATABASE2_NAME`{{% /code-placeholder-key %}}: your {{< product-name >}} [database](/influxdb3/enterprise/admin/databases/) +- {{% code-placeholder-key %}}`ADMIN TOKEN`{{% /code-placeholder-key %}}: the [admin token](/influxdb3/enterprise/admin/tokens/admin/) for your {{% product-name %}} instance +{{% code-placeholders "DATABASE_NAME|DATABASE2_NAME|ADMIN_TOKEN" %}} + +#### Create a token with read and write access to a database + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[influxdb3](#) +[HTTP API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +```bash +influxdb3 create token \ + --permission \ + --name "Read/write token for DATABASE_NAME" \ + db:DATABASE_NAME:read,write +``` + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```bash +curl \ + "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header "Authorization: Bearer ADMIN_TOKEN" \ + --data '{ + "token_name": "Read/write token for DATABASE_NAME", + "permissions": [{ + "resource_type": "db", + "resource_identifier": ["DATABASE_NAME"], + "actions": ["read","write"] + }] + }' +``` + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +#### Create a token with read and write access to all databases + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[influxdb3](#) +[HTTP API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +```bash +influxdb3 create token \ + --permission \ + --name "Read/write token for all databases" \ + db:*:read,write +``` + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```bash +curl \ + "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header "Authorization: Bearer ADMIN_TOKEN" \ + --data '{ + "token_name": "Read/write token for all databases", + "permissions": [{ + "resource_type": "db", + "resource_identifier": ["*"], + "actions": ["read","write"] + }] + }' +``` + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +#### Create a token with read-only access to a database + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[influxdb3](#) +[HTTP API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +```bash +influxdb3 create token \ + --permission \ + --name "Read-only token for DATABASE_NAME" \ + db:DATABASE_NAME:read +``` + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```bash +curl \ + "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header "Authorization: Bearer ADMIN_TOKEN" \ + --data '{ + "token_name": "Read-only token for DATABASE_NAME", + "permissions": [{ + "resource_type": "db", + "resource_identifier": ["DATABASE_NAME"], + "actions": ["read"] + }] + }' +``` + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +#### Create a token with read-only access to multiple databases + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[influxdb3](#) +[HTTP API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +```bash +influxdb3 create token \ + --permission \ + --name "Read-only token for DATABASE_NAME and DATABASE2_NAME" \ + db:DATABASE_NAME,DATABASE2_NAME:read +``` + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```bash +curl \ + "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header "Authorization: Bearer ADMIN_TOKEN" \ + --data '{ + "token_name": "Read-only token for DATABASE_NAME and DATABASE2_NAME", + "permissions": [{ + "resource_type": "db", + "resource_identifier": ["DATABASE_NAME","DATABASE2_NAME"], + "actions": ["read"] + }] + }' +``` + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +#### Create a token that expires in seven days + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[influxdb3](#) +[HTTP API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +```bash +influxdb3 create token \ + --permission \ + --expiry 7d \ + --name "Read/write token for DATABASE_NAME with 7d expiration" \ + db:DATABASE_NAME:read,write +``` + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```bash +curl \ + "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header "Authorization: Bearer ADMIN_TOKEN" \ + --data '{ + "token_name": "Read/write token for DATABASE_NAME with 7d expiration", + "permissions": [{ + "resource_type": "db", + "resource_identifier": ["DATABASE_NAME"], + "actions": ["read","write"] + }], + "expiry_secs": 604800 + }' +``` + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /code-placeholders %}} + +## Create a system token + +System tokens have the `system` resource type and allow for read-only access +to system information and metrics from your server. + +You can create system tokens for the following system resources: + +- `health`: system health information from the `/health` HTTP API endpoint +- `metrics`: system metrics information from the `/metrics` HTTP API endpoint +- `ping`: system ping information from the `/ping` HTTP API endpoint + +{{< tabs-wrapper >}} +{{% tabs %}} +[influxdb3](#) +[HTTP API](#) +{{% /tabs %}} +{{% tab-content %}} + + + +Use the [`influxdb3 create token` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/) +to create a system token with permissions for reading system information from +your {{% product-name %}} instance. + +In your terminal, run the `influxdb3 create token` command and provide the following: + + - `--permission` flag to create a token with permissions + - `--name` flag with a unique description of the token + - _Options_, for example: + - `--expiry` option with the token expiration time as a [duration](/influxdb3/enterprise/reference/glossary/#duration). + If an expiration isn't set, the token does not expire until revoked. + - Token permissions in the `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example: + - system:health:read + - `system:`: The `system` resource type, which specifies the token is for system information. + - `health`: The specific system resource to grant permissions to. + - `read`: The permission to grant to the token (system tokens are always read-only). + +{{% code-placeholders "1y" %}} + +```bash +influxdb3 create token \ +--permission \ +--expiry 1y \ +--name "System health token" \ +"system:health:read" +``` + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`1y`{{% /code-placeholder-key %}}: + the token expiration time as a + [duration](/influxdb3/enterprise/reference/glossary/#duration). + +The output is the token string in plain text. + + +{{% /tab-content %}} +{{% tab-content %}} + +Send a request to the following {{% product-name %}} endpoint: + +{{% api-endpoint endpoint="http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" method="post" %}} + +Provide the following request headers: + +- `Accept: application/json` to ensure the response body is JSON content +- `Content-Type: application/json` to indicate the request body is JSON content +- `Authorization: Bearer` and the [admin token](/influxdb3/enterprise/admin/tokens/admin/) + for your instance to authorize the request + +In the request body, provide the following parameters: + +- `token_name`: a description of the token, unique within the instance +- `resource_type`: the resource type for the token, which is `system` for system tokens +- `resource_identifier`: an array of system resource names to grant permissions to + - The resource identifier field supports the `*` wildcard, which grants read or write + permissions to all system information resources. +- `permissions`: an array of token permission actions (only `"read"` for system tokens) +- `expiry_secs`: Specify the token expiration time in seconds. + +The following example shows how to use the HTTP API to create a system token: + +{{% code-placeholders "300000" %}} + +```bash +curl \ +"http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \ +--header 'Accept: application/json' \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer ADMIN_TOKEN" \ +--data '{ + "token_name": "System health token", + "permissions": [{ + "resource_type": "system", + "resource_identifier": ["health"], + "actions": ["read"] + }], + "expiry_secs": 300000 +}' +``` + +{{% /code-placeholders %}} + +Replace the following in your request: + +- {{% code-placeholder-key %}}`300000`{{% /code-placeholder-key %}}: + the token expiration time in seconds. + +The response body contains token details, including the `token` field with the +token string in plain text. + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + + +## Output format + +The `influxdb3 create token` command supports the `--format json` option. +By default, the command outputs the token string. +For [token details](/influxdb3/enterprise/api/management/#operation/CreateDatabaseToken) and easier programmatic access to the command output, include `--format json` +with your command to format the output as JSON. + +The `/api/v3/configure/token` endpoint outputs JSON format in the response body. diff --git a/content/influxdb3/enterprise/admin/tokens/resource/list.md b/content/influxdb3/enterprise/admin/tokens/resource/list.md index 9c3f54924..15e052584 100644 --- a/content/influxdb3/enterprise/admin/tokens/resource/list.md +++ b/content/influxdb3/enterprise/admin/tokens/resource/list.md @@ -1,11 +1,11 @@ --- -title: List database tokens +title: List resource tokens description: > Use the `influxdb3 show tokens` command - to list database tokens in your InfluxDB 3 Enterprise instance. + to list resource tokens in your InfluxDB 3 Enterprise instance. menu: influxdb3_enterprise: - parent: Database tokens + parent: Resource tokens weight: 202 list_code_example: | ##### CLI @@ -14,23 +14,14 @@ list_code_example: | --token ADMIN_TOKEN --host http://{{< influxdb/host >}} ``` - - ##### API - ```bash - curl \ - --location "http://{{< influxdb/host >}}/api/v3/configure/tokens" \ - --header "Accept: application/json" \ - --header "Authorization: Bearer ADMIN_TOKEN" - ``` - aliases: - /influxdb3/enterprise/admin/tokens/list/ related: - /influxdb3/enterprise/reference/cli/influxdb3/token/list/ - /influxdb3/enterprise/reference/api/ -source: /shared/influxdb3-admin/tokens/database/list.md +source: /shared/influxdb3-admin/tokens/admin/list.md --- \ No newline at end of file