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 <stirnamanj@gmail.com>

---------

Co-authored-by: Jason Stirnaman <stirnamanj@gmail.com>

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
 

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/)

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:
+
+<!--pytest.mark.skip-->
+```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

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

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**.
+
+<!-- TODO: Add screenshot of token creation form -->
+<!-- {{< img-hd src="/img/telegraf/controller/create-token.png" alt="Telegraf Controller create token form" />}} -->
+
+> [!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/).

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.

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.

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.

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:
+
+<!--pytest.mark.skip-->
+```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_<token>
+```
+
+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.

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