docs-v2

17 KiB

Raw Permalink Blame History

title

description

weight

list_code_example

alt_links

Create a resource token

Use the [`influxdb3 create token --permission` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/) or the [HTTP API](/influxdb3/enterprise/api/v3/) to create fine-grained permissions tokens that grant access to resources such as databases and system information. Database tokens allow for reading and writing data in your {{< product-name omit="Clustered" >}} instance. System tokens allow for reading system information and metrics for your server.

influxdb3_enterprise

parent
Resource tokens

201

##### CLI ```bash influxdb3 create token \ --permission "db:DATABASE1,DATABASE2:read,write" \ --name "Read-write on DATABASE1, DATABASE2" \ --token ADMIN_TOKEN \ --expiry 1y ``` ##### HTTP API ```bash curl \ "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header "Authorization: Bearer AUTH_TOKEN" \ --data '{ "token_name": "Read-write for DATABASE1, DATABASE2", "permissions": [{ "resource_type": "db", "resource_identifier": ["DATABASE1","DATABASE2"], "actions": ["read","write"] }], "expiry_secs": 300000 }' ```

cloud-dedicated	cloud-serverless
/influxdb3/enterprise/admin/tokens/create-token/	/influxdb3/cloud-serverless/admin/tokens/create-token/

Use the influxdb3 create token --permission command or the /api/v3/configure/token HTTP API endpoint to create fine-grained permissions tokens that grant access to resources such as databases and system information. Database tokens allow for reading and writing data in your {{< product-name omit="Clustered" >}} instance. System tokens allow for reading system information and metrics for your server.

After you create an admin token, you can use the token string to authenticate influxdb3 commands and HTTP API requests for managing database and system tokens.

The HTTP API examples in this guide use cURL to send an API request, but you can use any HTTP client.

[!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 %}} CLI HTTP API {{% /tabs %}} {{% tab-content %}}

Use the influxdb3 create token --permission command to create a database token with fine-grained permissions for reading and writing data in your {{% product-name %}} instance.

In your terminal, enter influxdb3 create token and provide the following:

--permission: Token permissions (read, 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: A comma-separated list of database names to grant permissions to. The resource names part supports the * wildcard, which grants read or write permissions to all databases.
- read,write: A comma-separated list of permissions to grant to the token.
--name: A unique name for the token
Options, for example:
- --expiry: The token expiration time as a duration. If an expiration isn't set, the token does not expire until revoked. {{% code-placeholders "Read-write on DATABASE1, DATABASE2|DATABASE1,DATABASE2|1y|read,write" %}}

influxdb3 create token \
  --permission "db:DATABASE1,DATABASE2:read,write" \
  --name "Read-write on DATABASE1, DATABASE2" \
  --expiry 1y

Replace the following:

{{% code-placeholder-key %}}DATABASE1{{% /code-placeholder-key %}}, {{% code-placeholder-key %}}DATABASE2{{% /code-placeholder-key %}}: your {{% product-name %}} database
{{% code-placeholder-key %}}1y{{% /code-placeholder-key %}}: the token expiration time as a duration

The output is the token string in plain text.

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 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:

  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
  }'

Replace the following in your request:

{{% code-placeholder-key %}}DATABASE1{{% /code-placeholder-key %}}, {{% code-placeholder-key %}}DATABASE2{{% /code-placeholder-key %}}: your {{% product-name %}} database
{{% 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.

Examples

Create a token with read and write access to a database
Create a token with read and write access to all databases
Create a token with read-only access to a database
Create a token with read-only access to multiple databases
Create a token that expires in seven days

In the examples below, replace the following:

{{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: your {{< product-name >}} database
{{% code-placeholder-key %}}DATABASE2_NAME{{% /code-placeholder-key %}}: your {{< product-name >}} database
{{% code-placeholder-key %}}AUTH_TOKEN{{% /code-placeholder-key %}}: the {{% token-link "" "admin" %}} for your {{% product-name %}} instance

Create a token with read and write access to a database

{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} {{< code-tabs-wrapper >}} {{% code-tabs %}} CLI HTTP API {{% /code-tabs %}} {{% code-tab-content %}}

influxdb3 create token \
  --permission "db:DATABASE_NAME:read,write" \
  --name "Read/write token for DATABASE_NAME"

curl \
  "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer AUTH_TOKEN" \
  --data '{
    "token_name": "Read/write token for DATABASE_NAME",
    "permissions": [{
      "resource_type": "db",
      "resource_identifier": ["DATABASE_NAME"],
      "actions": ["read","write"]
    }]
  }'

Create a token with read and write access to all databases

{{% code-placeholders "AUTH_TOKEN" %}} {{< code-tabs-wrapper >}} {{% code-tabs %}} CLI HTTP API {{% /code-tabs %}} {{% code-tab-content %}}

influxdb3 create token \
  --permission "db:*:read,write" \
  --name "Read/write token for all databases"

curl \
  "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer AUTH_TOKEN" \
  --data '{
    "token_name": "Read/write token for all databases",
    "permissions": [{
      "resource_type": "db",
      "resource_identifier": ["*"],
      "actions": ["read","write"]
    }]
  }'

Create a token with read-only access to a database

{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} {{< code-tabs-wrapper >}} {{% code-tabs %}} CLI HTTP API {{% /code-tabs %}} {{% code-tab-content %}}

influxdb3 create token \
  --permission "db:DATABASE_NAME:read" \
  --name "Read-only token for DATABASE_NAME"

curl \
  "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer AUTH_TOKEN" \
  --data '{
    "token_name": "Read-only token for DATABASE_NAME",
    "permissions": [{
      "resource_type": "db",
      "resource_identifier": ["DATABASE_NAME"],
      "actions": ["read"]
    }]
  }'

Create a token with read-only access to multiple databases

{{% code-placeholders "DATABASE_NAME|DATABASE2_NAME|AUTH_TOKEN" %}} {{< code-tabs-wrapper >}} {{% code-tabs %}} CLI HTTP API {{% /code-tabs %}} {{% code-tab-content %}}

influxdb3 create token \
  --permission "db:DATABASE_NAME,DATABASE2_NAME:read" \
  --name "Read-only token for DATABASE_NAME, DATABASE2_NAME"

curl \
  "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer AUTH_TOKEN" \
  --data '{
    "token_name": "Read-only token for DATABASE_NAME, DATABASE2_NAME",
    "permissions": [{
      "resource_type": "db",
      "resource_identifier": ["DATABASE_NAME","DATABASE2_NAME"],
      "actions": ["read"]
    }]
  }'

Create a token that expires in seven days

{{% code-placeholders "DATABASE_NAME|7d|604800|AUTH_TOKEN" %}} {{< code-tabs-wrapper >}} {{% code-tabs %}} CLI HTTP API {{% /code-tabs %}} {{% code-tab-content %}}

influxdb3 create token \
  --permission "db:DATABASE_NAME:read,write" \
  --name "Read/write token for DATABASE_NAME with 7d expiration" \
  --expiry 7d

curl \
  "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer AUTH_TOKEN" \
  --data '{
    "token_name": "Read/write token for DATABASE_NAME with 7d expiration",
    "permissions": [{
      "resource_type": "db",
      "resource_identifier": ["DATABASE_NAME"],
      "actions": ["read","write"]
    }],
    "expiry_secs": 604800
  }'

Create a system token

System tokens have the system resource type and allow for read-only access to system information and metrics from your server.

You can create system tokens for the following system resources:

health: system health information from the /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 %}} CLI HTTP API {{% /tabs %}} {{% tab-content %}}

Use the influxdb3 create token command to create a system token with permissions for reading system information from your {{% product-name %}} instance.

In your terminal, run the influxdb3 create token --permission command and provide the following:

--name: A unique name for the token
Options, for example:
- --expiry: The token expiration time as a duration. If an expiration isn't set, the token does not expire until revoked.
Token permissions in the RESOURCE_TYPE:RESOURCE_NAMES: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).

influxdb3 create token \
  --permission "system:health:read" \
  --name "System health token" \
  --expiry 1y