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

adds database token expiration to dedicated and clustered docs

influxctl-token-expiration
Scott Anderson 2025-03-27 10:05:04 -06:00
parent 00858380f6
commit 81b134b71f
3 changed files with 278 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
content/influxdb3/cloud-dedicated/admin/tokens/database/create.md
View File

@ -16,6 +16,7 @@ list_code_example: |
--read-database DATABASE1_NAME \
--read-database DATABASE2_NAME \
--write-database DATABASE2_NAME \
--expires-at 2030-01-01T00:00:00Z \
"Read-only on DATABASE1_NAME, Read/write on DATABASE2_NAME"
```
@ -37,7 +38,9 @@ list_code_example: |
"action": "read",
"resource": "DATABASE_NAME"
}
]
],
"expirationType": "datetime",
"expiresAt": "2030-01-01T00:00:00Z"
}'
```
aliases:
@ -60,6 +63,7 @@ or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/) to crea
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXCTL ----------------------------->
Use the [`influxctl token create` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/token/create/)
to create a token that grants access to databases in your {{% product-name omit=" Clustered" %}} cluster.
@ -76,20 +80,25 @@ to create a token that grants access to databases in your {{% product-name omit=
- Token description
{{% code-placeholders "DATABASE_NAME|TOKEN_DESCRIPTION" %}}
{{% code-placeholders "DATABASE_NAME|TOKEN_DESCRIPTION|RFC3339_TIMESTAMP" %}}
```sh
influxctl token create \
--read-database DATABASE_NAME \
--write-database DATABASE_NAME \
"Read/write token for DATABASE_NAME"
--expires-at RFC3339_TIMESTAMP \
"Read/write token for DATABASE_NAME"
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} [database](/influxdb3/cloud-dedicated/admin/databases/)
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
your {{% product-name %}} [database](/influxdb3/cloud-dedicated/admin/databases/)
- {{% code-placeholder-key %}}`RFC3339_TIMESTAMP`{{% /code-placeholder-key %}}:
the token expiration date and time in
[RFC3339 format](/influxdb3/cloud-dedicated/reference/glossary/#rfc3339-timestamp).
The output is the token ID and the token string.
**This is the only time the token string is available in plain text.**
@ -122,6 +131,12 @@ _This example uses [cURL](https://curl.se/) to send a Management HTTP API reques
- `"action"`: Specify `read` or `write` permission to the database.
- `"resource"`: Specify the database name.
- `description`: Provide a description of the token.
- `expirationType`: Specify `datetime` or `noExpiration` token expiration type.
- `expiresAt`: Specify the token expiration date and time in
[RFC3339 format](/influxdb3/cloud-dedicated/reference/glossary/#rfc3339-timestamp).
> [!Note]
> `expiresAt` is only required when `expirationType` is `datetime`.
The following example shows how to use the Management API to create a database token:
@ -144,7 +159,9 @@ curl \
"action": "read",
"resource": "DATABASE_NAME"
}
]
],
"expirationType": "datetime",
"expiresAt": "2030-01-01T00:00:00Z"
}'
```
@ -195,6 +212,7 @@ The Management API outputs JSON format in the response body.
- [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:
@ -241,7 +259,8 @@ curl \
"action": "read",
"resource": "DATABASE_NAME"
}
]
],
"expirationType": "noExpiration"
}'
```
@ -435,3 +454,124 @@ curl \
{{% /code-placeholders %}}
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
### Create a token that expires in seven days
{{< tabs-wrapper >}}
{{% tabs "small" %}}
[Linux](#)
[macOS](#)
{{% /tabs %}}
{{% tab-content %}}
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[influxctl](#)
[Management API](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_NAME" %}}
<!-- pytest.mark.skip -->
```bash
influxctl token create \
--read-database DATABASE_NAME \
--write-database DATABASE_NAME \
--expires-at $(date -d "+7 days" +"%Y-%m-%dT%H:%M:%S%z") \
"Read/write token for DATABASE_NAME with 7d expiration"
```
{{% /code-placeholders %}}
{{% /code-tab-content %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_NAME" %}}
```sh
curl \
--location "https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/tokens" \
--header "Accept: application/json" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer MANAGEMENT_TOKEN" \
--data "{
\"description\": \"Read/write token for DATABASE_NAME\",
\"permissions\": [
{
\"action\": \"write\",
\"resource\": \"DATABASE_NAME\"
},
{
\"action\": \"read\",
\"resource\": \"DATABASE_NAME\"
}
],
\"expirationType\": \"datetime\",
\"expiresAt:\" \"$(date -d "+7 days" +"%Y-%m-%dT%H:%M:%S%z")\"
}"
```
{{% /code-placeholders %}}
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
{{% /tab-content %}}
{{% tab-content %}}
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[influxctl](#)
[Management API](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_NAME" %}}
<!-- pytest.mark.skip -->
```bash
influxctl token create \
--read-database DATABASE_NAME \
--write-database DATABASE_NAME \
--expires-at $(gdate -d "+7 days" +"%Y-%m-%dT%H:%M:%S%z") \
"Read/write token for DATABASE_NAME with 7d expiration"
```
{{% /code-placeholders %}}
{{% /code-tab-content %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_NAME" %}}
```sh
curl \
--location "https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/tokens" \
--header "Accept: application/json" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer MANAGEMENT_TOKEN" \
--data "{
\"description\": \"Read/write token for DATABASE_NAME\",
\"permissions\": [
{
\"action\": \"write\",
\"resource\": \"DATABASE_NAME\"
},
{
\"action\": \"read\",
\"resource\": \"DATABASE_NAME\"
}
],
\"expirationType\": \"datetime\",
\"expiresAt:\" \"$(gdate -d "+7 days" +"%Y-%m-%dT%H:%M:%S%z")\"
}"
```
{{% /code-placeholders %}}
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
{{% /tab-content %}}
{{< /tabs-wrapper >}}

63
content/influxdb3/clustered/admin/tokens/database/create.md
View File

@ -14,6 +14,7 @@ list_code_example: |
--read-database DATABASE1_NAME \
--read-database DATABASE2_NAME \
--write-database DATABASE2_NAME \
--expires-at 2030-01-01T00:00:00Z \
"Read-only on DATABASE1_NAME, Read/write on DATABASE2_NAME"
```
aliases:
@ -28,38 +29,50 @@ to create a token that grants access to databases in your {{% product-name omit=
1. If you haven't already, [download and install the `influxctl` CLI](/influxdb3/clustered/reference/cli/influxctl/#download-and-install-influxctl).
2. In your terminal, run the `influxctl token create` command and provide the following:
- Token permissions (read and write)
- `--read-database`: Grants read permissions to the specified database. Repeatable.
- `--write-database`: Grants write permissions to the specified database. Repeatable.
Both of these flags support the `*` wildcard which grants read or write
permissions to all databases. Enclose wildcards in single or double
quotes--for example: `'*'` or `"*"`.
- Token expiration date and time in [RFC3339 format](/influxdb3/clustered/reference/glossary/#rfc3339-timestamp).
_If you do not provide an expiration, the token does not expire._
- Token description
{{% code-placeholders "DATABASE_NAME|TOKEN_DESCRIPTION" %}}
{{% code-placeholders "DATABASE_NAME|TOKEN_DESCRIPTION|RFC3339_TIMESTAMP" %}}
```sh
influxctl token create \
--read-database DATABASE_NAME \
--write-database DATABASE_NAME \
"Read/write token for DATABASE_NAME"
--expires-at RFC3339_TIMESTAMP \
"Read/write token for DATABASE_NAME"
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} [database](/influxdb3/clustered/admin/databases/)
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
your {{% product-name %}} [database](/influxdb3/clustered/admin/databases/)
- {{% code-placeholder-key %}}`RFC3339_TIMESTAMP`{{% /code-placeholder-key %}}:
the token expiration date and time in
[RFC3339 format](/influxdb3/clustered/reference/glossary/#rfc3339-timestamp).
The output is the token ID and the token string.
**This is the only time the token string is available in plain text.**
## Notable behaviors
- InfluxDB might take some time--from a few seconds to a few minutes--to activate and synchronize new tokens.
If a new database token doesn't immediately work (you receive a `401 Unauthorized` error) for querying or writing, wait and then try again.
- InfluxDB might take some time--from a few seconds to a few minutes--to
activate and synchronize new tokens.
If a new database token doesn't immediately work (you receive a `401 Unauthorized` error)
for querying or writing, wait and then try again.
- Token strings are viewable _only_ on token creation.
> [!Note]
@ -86,6 +99,7 @@ with your command to format the output as JSON.
- [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:
@ -152,3 +166,42 @@ influxctl token create \
```
{{% /code-placeholders %}}
### Create a token that expires in seven days
{{% code-placeholders "DATABASE_NAME" %}}
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Linux](#)
[macOS](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```bash
influxctl token create \
--read-database DATABASE_NAME \
--write-database DATABASE_NAME \
--expires-at $(date -d "+7 days" +"%Y-%m-%dT%H:%M:%S%z") \
"Read/write token for DATABASE_NAME with 7d expiration"
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```bash
influxctl token create \
--read-database DATABASE_NAME \
--write-database DATABASE_NAME \
--expires-at $(gdate -d "+7 days" +"%Y-%m-%dT%H:%M:%S%z") \
"Read/write token for DATABASE_NAME with 7d expiration"
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
{{% /code-placeholders %}}

82
content/influxdb3/clustered/reference/cli/influxctl/token/create.md
View File

@ -17,14 +17,22 @@ The `--read-database` and `--write-database` flags support the `*` wildcard
which grants read or write permissions to all databases. Enclose wildcards in
single or double quotes--for example: `'*'` or `"*"`.
The `--expires-at` flag specifies the data and time a token should expire.
Provide an [RFC3339 timestamp](/influxdb3/clustered/reference/glossary/#rfc3339-timestamp).
> [!Important]
> If you don't specify a token expiration, the token never expires.
The `--format` flag lets you print the output in other formats.
The `json` format is available for programmatic parsing by other tooling.
Default: `table`.
## Notable behaviors
- InfluxDB might take some time--from a few seconds to a few minutes--to activate and synchronize new tokens.
If a new database token doesn't immediately work (you receive a `401 Unauthorized` error) for querying or writing, wait and then try again.
- InfluxDB might take some time--from a few seconds to a few minutes--to
activate and synchronize new tokens. If a new database token doesn't
immediately work (you receive a `401 Unauthorized` error) for querying or
writing, wait and then try again.
- Token strings are viewable _only_ on token creation.
> [!Note]
@ -36,10 +44,13 @@ If a new database token doesn't immediately work (you receive a `401 Unauthorize
## Usage
```sh
<!-- pytest.mark.skip -->
```bash
influxctl token create \
[--read-database=<DATABASE_NAME>] \
[--write-database=<DATABASE_NAME>] \
[--expires-at=<RFC3339_DATE>] \
<TOKEN_DESCRIPTION>
```
@ -53,6 +64,7 @@ influxctl token create \
| Flag | | Description |
| :--- | :----------------- | :--------------------------------------------------- |
| | `--expires-at` | Token expiration date and time in RFC3339 format |
| | `--format` | Output format (`table` _(default)_ or `json`) |
| | `--read-database` | Grant read permissions to a database _(Repeatable)_ |
| | `--write-database` | Grant write permissions to a database _(Repeatable)_ |
@ -69,6 +81,7 @@ _Also see [`influxctl` global flags](/influxdb3/clustered/reference/cli/influxct
- [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-on-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:
@ -79,7 +92,10 @@ In the examples below, replace the following:
### Create a token with read and write access to a database
{{% code-placeholders "DATABASE_NAME" %}}
```sh
<!-- pytest.mark.skip -->
```bash
influxctl token create \
--read-database DATABASE_NAME \
--write-database DATABASE_NAME \
@ -89,7 +105,9 @@ influxctl token create \
### Create a token with read and write access to all databases
```sh
<!-- pytest.mark.skip -->
```bash
influxctl token create \
--read-database "*" \
--write-database "*" \
@ -99,7 +117,10 @@ influxctl token create \
### Create a token with read-only access to a database
{{% code-placeholders "DATABASE_NAME" %}}
```sh
<!-- pytest.mark.skip -->
```bash
influxctl token create \
--read-database DATABASE_NAME \
"Read-only token for DATABASE_NAME"
@ -109,7 +130,10 @@ influxctl token create \
### Create a token with read-only access to multiple databases
{{% code-placeholders "DATABASE_NAME|DATABASE2_NAME" %}}
```sh
<!-- pytest.mark.skip -->
```bash
influxctl token create \
--read-database DATABASE_NAME \
--read-database DATABASE2_NAME \
@ -120,7 +144,10 @@ influxctl token create \
### Create a token with mixed permissions to multiple databases
{{% code-placeholders "DATABASE_NAME|DATABASE2_NAME" %}}
```sh
<!-- pytest.mark.skip -->
```bash
influxctl token create \
--read-database DATABASE_NAME \
--read-database DATABASE2_NAME \
@ -128,3 +155,42 @@ influxctl token create \
"Read-only on DATABASE_NAME, read/write on DATABASE2_NAME"
```
{{% /code-placeholders %}}
### Create a token that expires in seven days
{{% code-placeholders "DATABASE_NAME" %}}
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Linux](#)
[macOS](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```bash
influxctl token create \
--read-database DATABASE_NAME \
--write-database DATABASE_NAME \
--expires-at $(date -d "+7 days" +"%Y-%m-%dT%H:%M:%S%z") \
"Read/write token for DATABASE_NAME with 7d expiration"
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```bash
influxctl token create \
--read-database DATABASE_NAME \
--write-database DATABASE_NAME \
--expires-at $(gdate -d "+7 days" +"%Y-%m-%dT%H:%M:%S%z") \
"Read/write token for DATABASE_NAME with 7d expiration"
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
{{% /code-placeholders %}}