From eacd21a2bae9698ced72166b800cb85f3db166bc Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Thu, 12 Mar 2026 08:27:58 -0600 Subject: [PATCH] chore(tc-tokens): add API token docs for telegraf controller (#6927) * chore(tc-tokens): update code placeholder syntax * Apply suggestions from code review Co-authored-by: Jason Stirnaman --------- Co-authored-by: Jason Stirnaman --- content/telegraf/controller/agents/create.md | 21 ++++- content/telegraf/controller/configs/create.md | 14 ++++ content/telegraf/controller/configs/use.md | 18 ++++ content/telegraf/controller/tokens/_index.md | 69 +++++++++++++++ content/telegraf/controller/tokens/create.md | 64 ++++++++++++++ content/telegraf/controller/tokens/delete.md | 60 ++++++++++++++ .../telegraf/controller/tokens/reassign.md | 64 ++++++++++++++ content/telegraf/controller/tokens/revoke.md | 61 ++++++++++++++ content/telegraf/controller/tokens/use.md | 83 +++++++++++++++++++ content/telegraf/controller/users/_index.md | 3 + 10 files changed, 455 insertions(+), 2 deletions(-) create mode 100644 content/telegraf/controller/tokens/_index.md create mode 100644 content/telegraf/controller/tokens/create.md create mode 100644 content/telegraf/controller/tokens/delete.md create mode 100644 content/telegraf/controller/tokens/reassign.md create mode 100644 content/telegraf/controller/tokens/revoke.md create mode 100644 content/telegraf/controller/tokens/use.md diff --git a/content/telegraf/controller/agents/create.md b/content/telegraf/controller/agents/create.md index 55faf4a9c..f9fdbf49c 100644 --- a/content/telegraf/controller/agents/create.md +++ b/content/telegraf/controller/agents/create.md @@ -41,7 +41,9 @@ The following heartbeat plugin configuration options are available: - **url**: _({{% req %}})_ URL of heartbeat endpoint. - **instance_id**: _({{% req %}})_ Unique identifier for the Telegraf instance or agent (also known as the agent ID). -- **token**: Authorization token for the heartbeat endpoint +- **token**: _({{% req text="Required with auth enabled" %}})_ + {{% product-name %}} API token for the heartbeat endpoint. + The token must have **write** permissions on the **Heartbeat** API. - **interval**: Interval for sending heartbeat messages. Default is `1m` (every minute). - **include**: Information to include in the heartbeat message. Available options are: @@ -56,18 +58,33 @@ The following heartbeat plugin configuration options are available: ### Example heartbeat output plugin The following is an example heartbeat output plugin configuration that uses -an `agent_id` [configuration parameter](#) to specify the `instance_id`. +an `agent_id` [configuration parameter](/telegraf/controller/configs/dynamic-values/#parameters) +to specify the `instance_id`. +{{% telegraf/dynamic-values %}} ```toml [[outputs.heartbeat]] url = "http://telegraf_controller.example.com/agents/heartbeat" instance_id = "&{agent_id}" + token = "${INFLUX_TOKEN}" interval = "1m" include = ["hostname", "statistics", "configs"] [outputs.heartbeat.headers] User-Agent = "telegraf" ``` +{{% /telegraf/dynamic-values %}} + +> [!Important] +> #### Authorize heartbeats using an API token +> +> If {{% product-name %}} requires authorization on the **Heartbeat** API, +> include the `token` option in your heartbeat plugin configuration. +> Provide a {{% product-name %}} token with **write** permissions on the +> **Heartbeat** API. +> +> We recommend defining the `INFLUX_TOKEN` environment variable when starting +> Telegraf and using that to define the token in your heartbeat plugin. ## Verify a new agent diff --git a/content/telegraf/controller/configs/create.md b/content/telegraf/controller/configs/create.md index 3d477a9e5..8edaec09c 100644 --- a/content/telegraf/controller/configs/create.md +++ b/content/telegraf/controller/configs/create.md @@ -65,17 +65,31 @@ configuration with a [Telegraf heartbeat output plugin](/telegraf/v1/output-plug This plugin reports agent information back to the {{% product-name %}} heartbeat API and lets you monitor the health of your deployed Telegraf agents. +{{% telegraf/dynamic-values %}} ```toml [[outputs.heartbeat]] url = "http://localhost:8000/agents/heartbeat" instance_id = "&{agent_id}" interval = "1m" include = ["hostname", "statistics", "configs"] +token = "${INFLUX_TOKEN}" ``` +{{% /telegraf/dynamic-values %}} To monitor agents with {{% product-name %}}, include a heartbeat plugin in your Telegraf configurations. +> [!Important] +> #### Authorize heartbeats using an API token +> +> If {{% product-name %}} requires authorization on the **Heartbeat** API, +> include the `token` option in your heartbeat plugin configuration. +> Provide a {{% product-name %}} token with **write** permissions on the +> **Heartbeat** API. +> +> We recommend defining the `INFLUX_TOKEN` environment variable when starting +> Telegraf and using that to define the token in your heartbeat plugin. + ## Next steps - Use [dynamic values](/telegraf/controller/configs/dynamic-values/) diff --git a/content/telegraf/controller/configs/use.md b/content/telegraf/controller/configs/use.md index ab10dab36..4d7e4fbb0 100644 --- a/content/telegraf/controller/configs/use.md +++ b/content/telegraf/controller/configs/use.md @@ -40,6 +40,24 @@ telegraf \ Telegraf retrieves and validates the configuration from {{% product-name %}} and then starts the `telegraf` process using the loaded configuration. +### Retrieve a configuration with authorization enabled + +If {{% product-name %}} is configured to require authentication on the **Configs** +API, define the `INFLUX_TOKEN` environment variable to authorize Telegraf +to retrieve a configuration: + + +```bash { placeholders="YOUR_TC_API_TOKEN" } +INLFLUX_TOKEN=YOUR_TC_API_TOKEN + +telegraf \ + --config "http://telegraf_controller.example.com/api/configs/xxxxxx/toml +``` + +Replace {{% code-placeholder-key %}}`YOUR_TC_API_TOKEN`{{% /code-placeholder-key %}} +with your {{% product-name %}} API token. This token must have **read** +permissions on the **Configs** API. + ## Set dynamic values Telegraf and {{% product-name %}} let you diff --git a/content/telegraf/controller/tokens/_index.md b/content/telegraf/controller/tokens/_index.md new file mode 100644 index 000000000..2a0d01f54 --- /dev/null +++ b/content/telegraf/controller/tokens/_index.md @@ -0,0 +1,69 @@ +--- +title: Manage API tokens +description: > + Create and manage API tokens for authenticating API requests and + Telegraf agent connections to Telegraf Controller. +menu: + telegraf_controller: + name: Manage API tokens +weight: 8 +cascade: + related: + - /telegraf/controller/reference/authorization/ +--- + +API tokens authenticate requests to the {{% product-name %}} API and Telegraf agent connections. +Use tokens to authorize Telegraf agents, heartbeat requests, and external API clients. + +## Token format + +All API tokens use the `tc-apiv1_` prefix, making them easy to identify in +configuration files and scripts. + +The full token value is displayed only once at the time of creation and cannot be retrieved later. +Copy and store the token in a secure location immediately after creating it. + +> [!Important] +> #### Raw token strings are not stored +> +> Tokens are stored as a cryptographic hash. The original value is never saved. +> If you lose a token, you must revoke it and create a new one. + +## Token permissions + +Each token is scoped to a specific user. +Token permissions are restricted to the permissions allowed by the user's role. +A token cannot exceed the permissions of the user it belongs to. + +When you create a token, you can set custom permissions to restrict the token's +access below your full role permissions. +This lets you issue narrowly scoped tokens for specific tasks, such as a token +that can only register agents or a token limited to read-only access. + +## Token states + +Tokens exist in one of two states: + +- **Active** -- The token can be used for authentication. +- **Revoked** -- The token is permanently disabled but the record is retained + for auditing purposes. + +Revoking a token is irreversible. +Any agent or client using a revoked token immediately loses access. + +## Token visibility + +Your role determines which tokens you can view and manage: + +| Role | Token visibility | +|:------------------|:----------------------------------| +| **Owner** | All tokens across all users | +| **Administrator** | All tokens across all users | +| **Manager** | Only their own tokens | +| **Viewer** | Cannot manage tokens | + +> [!Note] +> **Owner** and **Administrator** users can revoke any token in the organization, +> including tokens belonging to other users. + +{{< children hlevel="h2" >}} diff --git a/content/telegraf/controller/tokens/create.md b/content/telegraf/controller/tokens/create.md new file mode 100644 index 000000000..bdb69e58a --- /dev/null +++ b/content/telegraf/controller/tokens/create.md @@ -0,0 +1,64 @@ +--- +title: Create an API token +description: > + Create a new API token for authenticating with the Telegraf Controller API. +menu: + telegraf_controller: + name: Create a token + parent: Manage API tokens +weight: 101 +--- + +Create a new API token to authenticate requests to the {{% product-name %}} API. +Tokens let you grant scoped access to external tools, scripts, and services without sharing your login credentials. + +> [!Important] +> #### Required permissions +> +> You must have an **Owner**, **Administrator**, or **Manager** role assigned to +> your account. + +## Create a token + +1. Navigate to the **API Tokens** page. +2. Click **Create Token**. +3. Enter a **Description** for the token that identifies where or how the token + will be used. +4. _(Optional)_ Set an **Expiration** date. + Tokens without an expiration date remain active indefinitely. +5. _(Optional)_ Set **Custom permissions** to restrict the token's access below + your role's full permissions. + See [Custom permissions](#custom-permissions) for details. +6. Click **Create**. + + + + +> [!Important] +> #### Copy and store your token +> +> Copy your API token immediately after creation. +> The full token value is only displayed once and cannot be retrieved later. + +## Custom permissions + +When you set custom permissions on a token, {{% product-name %}} intersects +those permissions with your role's existing permissions. +This means you can use custom permissions to narrow a token's access, but you +cannot create a token with more access than your role allows. + +For example, if you have the **Manager** role, you cannot create a token with +user management permissions. +The resulting token will only include the permissions that overlap with what +your role grants. + +Custom permissions are useful when you want to issue a token for a specific task, +such as read-only access to configurations, without exposing the full scope of +your role. + +## If you lose a token + +If you lose or forget a token value, you cannot recover it. +Revoke the lost token and create a new one to restore access. + +For instructions on revoking a token, see [Revoke an API token](/telegraf/controller/tokens/revoke/). diff --git a/content/telegraf/controller/tokens/delete.md b/content/telegraf/controller/tokens/delete.md new file mode 100644 index 000000000..a686707d5 --- /dev/null +++ b/content/telegraf/controller/tokens/delete.md @@ -0,0 +1,60 @@ +--- +title: Delete a token +description: > + Permanently delete an API token from Telegraf Controller. +menu: + telegraf_controller: + name: Delete a token + parent: Manage API tokens +weight: 105 +--- + +Deleting a token immediately removes the token so it cannot be used for authentication. +Unlike revocation, deletion removes all data associated with the token and token +history. + +> [!Warning] +> #### Deleting and API token cannot be undone +> +> Deleting a token is permanent and cannot be undone. Any agents or clients +> using this token will lose access immediately. + +## Delete versus revoke + +{{% product-name %}} supports two ways to remove a token from active use: +**deletion** and **revocation**. + +- **Deleted** tokens are permanently removed from the system. + No record of the token is retained after deletion. +- **Revoked** tokens remain visible in the token list with a **Revoked** status. + This provides an audit trail showing when the token was created and when it + was disabled. Revoked tokens cannot be used for authentication. + +Use revoke when you want to disable a token but maintain an audit trail. +Use delete when you want to completely remove the token and its record from the system. + +For more information about revoking a token, see +[Revoke a token](/telegraf/controller/tokens/revoke/). + +## Delete a token + +1. Navigate to the **API Tokens** page or open the token's detail view. +2. Click **Delete** to initiate the deletion. If on the token detail + page, select the **Manage** tab to reveal the **Delete** action. +3. In the confirmation dialog, confirm that you want to permanently delete the token. + +Once confirmed, the token is immediately deleted. Any agent or integration +that relies on the deleted token will no longer be able to authenticate with +{{% product-name %}}. + +## Bulk delete tokens + +You can delete multiple tokens at once from the **API Tokens** page. + +1. On the **API Tokens** page, select the checkboxes next to each token you want to delete. +2. Click the **Delete** option in the bulk actions bar. +3. In the confirmation dialog, review the number of tokens to be deleted and confirm. + +All selected tokens are permanently removed and immediately invalidated. +Verify that no active agents depend on the selected tokens before confirming the +bulk deletion. diff --git a/content/telegraf/controller/tokens/reassign.md b/content/telegraf/controller/tokens/reassign.md new file mode 100644 index 000000000..0ed6a9137 --- /dev/null +++ b/content/telegraf/controller/tokens/reassign.md @@ -0,0 +1,64 @@ +--- +title: Reassign a token +description: > + Reassign an API token from one user to another in Telegraf Controller. +menu: + telegraf_controller: + name: Reassign a token + parent: Manage API tokens +weight: 103 +--- + +Reassigning an API token from one user to another in Telegraf Controller lets +you transfer ownership of that token to another user without disrupting any +external clients using the token. + +> [!Important] +> #### Required permissions +> +> To reassign an API token, you must have the **Owner** or **Administrator** +> role in {{% product-name %}}. + +## Reassign a token + +You can reassign an individual token from one user to another directly from the +token's detail view or the tokens list. + +1. In {{% product-name %}}, navigate to the **API Tokens** page or open the + detail page for the token you want to reassign. +2. Click **Reassign** on the token you want to transfer. If on the token detail + page, select the **Manage** tab to reveal the **Reassign** action. +3. In the dialog that appears, select the target user you want to assign the + token to. +4. Click **Confirm** to complete the reassignment. + +> [!Important] +> When you reassign a token, its permissions are automatically restricted to +> match the target user's role. For example, a token with full access reassigned +> to a Viewer becomes a read-only token. + +## Bulk reassign + +If you need to reassign multiple tokens at once, use the bulk reassign option. + +1. On the **API Tokens** page, select the checkboxes next to the tokens you want + to reassign. +2. Click the **Reassign** option in the bulk actions bar. +3. Select the target user you want to assign the selected tokens to. +4. Click **Confirm** to reassign all selected tokens. + +The same permission restriction applies during bulk reassignment. Each token's +permissions are adjusted to align with the target user's role. + +## When to reassign + +Reassigning tokens lets you transfer ownership without revoking and recreating +tokens. This is useful in several common scenarios: + +- **Offboarding a user**: A user is leaving the organization and their tokens + should continue working under another account. + Reassigning ensures active integrations are not disrupted. +- **Reorganizing responsibilities**: Team members are shifting roles or + responsibilities and token ownership should reflect the new structure. +- **Consolidating ownership after role changes**: After updating user roles, you + may want to consolidate tokens under a single account to simplify token management. diff --git a/content/telegraf/controller/tokens/revoke.md b/content/telegraf/controller/tokens/revoke.md new file mode 100644 index 000000000..c82556a74 --- /dev/null +++ b/content/telegraf/controller/tokens/revoke.md @@ -0,0 +1,61 @@ +--- +title: Revoke a token +description: > + Revoke an API token to immediately prevent its use while keeping + the token record for auditing. +menu: + telegraf_controller: + name: Revoke a token + parent: Manage API tokens +weight: 104 +--- + +Revoking a token immediately prevents it from being used for authentication +while keeping the token record in the system for auditing purposes. +Unlike deletion, revocation preserves a full history of the token, including +when it was created and when it was disabled. + +## Revoke versus delete + +{{% product-name %}} supports two ways to remove a token from active use: +**revocation** and **deletion**. + +- **Revoked** tokens remain visible in the token list with a **Revoked** status. + This provides an audit trail showing when the token was created and when it + was disabled. Revoked tokens cannot be used for authentication. +- **Deleted** tokens are permanently removed from the system. + No record of the token is retained after deletion. + +Use revoke when you want to disable a token but maintain an audit trail. +Use delete when you want to completely remove the token and its record from the system. + +For more information about deleting a token, see +[Delete a token](/telegraf/controller/tokens/delete/). + +## Revoke a token + +1. Navigate to the **API Tokens** page, or open the token's detail view. +2. Click **Revoke**. If on the token detail page, select the **Manage** tab to + reveal the **Revoke** action. +3. Confirm the revocation in the dialog. + +The token status changes to **Revoked** and any requests that use the token are +immediately rejected. + +> [!Note] +> #### You cannot reactivate a revoked token +> +> Revocation is permanent. You cannot re-activate a revoked token. +> If you need to restore access, create a new token. +> See [Create a token](/telegraf/controller/tokens/create/). + +## Bulk revoke + +To revoke multiple tokens at once: + +1. On the **API Tokens** page, select the tokens you want to revoke. +2. Click **Revoke** in the bulk actions bar. +3. Confirm the revocation in the dialog. + +All selected tokens are immediately revoked and can no longer be used for +authentication. diff --git a/content/telegraf/controller/tokens/use.md b/content/telegraf/controller/tokens/use.md new file mode 100644 index 000000000..13a1de890 --- /dev/null +++ b/content/telegraf/controller/tokens/use.md @@ -0,0 +1,83 @@ +--- +title: Use API tokens +description: > + Use API tokens to authenticate Telegraf agents, heartbeat requests, + and external API clients with Telegraf Controller. +menu: + telegraf_controller: + name: Use tokens + parent: Manage API tokens +weight: 102 +--- + +API tokens authenticate requests to {{% product-name %}}. +Use tokens to connect Telegraf agents, authorize heartbeat reporting, and +integrate external API clients. + +## With Telegraf agents + +Configure your Telegraf agent to include an API token when retrieving +configurations and reporting heartbeats to {{% product-name %}}. + +Telegraf agents require API tokens with the following permissions: + +- **Configs**: Read +- **Heartbeat**: Write + +### Use the INFLUX_TOKEN environment variable + +When retrieving a configuration from a URL, Telegraf only sends an `Authorization` +when it detects the `INFLUX_TOKEN` environment variable. To authorize Telegraf +to retrieve a configuration from {{% product-name %}}, define the `INFLUX_TOKEN` +environment variable: + + +```bash { placeholders="YOUR_TC_API_TOKEN" } +INFLUX_TOKEN=YOUR_TC_API_TOKEN + +telegraf \ + --config "http://telegraf_controller.example.com/api/configs/xxxxxx/toml +``` + +Replace {{% code-placeholder-key %}}`YOUR_TC_API_TOKEN`{{% /code-placeholder-key %}} +with your {{% product-name %}} API token. + +### For heartbeat requests + +Telegraf uses the [Heartbeat output plugin](/telegraf/v1/output-plugins/heartbeat/) +to send heartbeats to {{% product-name %}}. +Use the `INFLUX_TOKEN` environment variable to define the `token` option in your +heartbeat plugin configuration. +Telegraf uses the environment variable value defined when starting Telegraf. + +{{% telegraf/dynamic-values %}} +```toml +[[outputs.heartbeat]] + url = "http://telegraf_controller.example.com/agents/heartbeat" + instance_id = "&{agent_id}" + interval = "1m" + include = ["hostname", "statistics", "configs"] + token = "${INFLUX_TOKEN}" +``` +{{% /telegraf/dynamic-values %}} + +When authentication is required for the heartbeat endpoint, agents must include +a valid token with each heartbeat request. +If a heartbeat request is missing a token or includes an invalid token, +{{% product-name %}} rejects the request and the agent's status is not updated. + +## With external API clients + +Include the token in the `Authorization` header when making API requests to +{{% product-name %}}: + +``` +Authorization: Bearer tc-apiv1_ +``` + +The token's permissions determine which API endpoints and operations are accessible. +Requests made with a token that lacks the required permissions are rejected with an authorization error. + +> [!Note] +> If authentication is disabled for an endpoint group in **Settings**, requests to those endpoints do not require a token. +> See [Settings](/telegraf/controller/settings/#require-authentication-per-endpoint) for details on configuring authentication requirements per endpoint. diff --git a/content/telegraf/controller/users/_index.md b/content/telegraf/controller/users/_index.md index 707fe356d..5e67959dd 100644 --- a/content/telegraf/controller/users/_index.md +++ b/content/telegraf/controller/users/_index.md @@ -7,6 +7,9 @@ menu: telegraf_controller: name: Manage users weight: 7 +cascade: + related: + - /telegraf/controller/reference/authorization/ --- Users are accounts that can log into the {{% product-name %}} web interface and