Use API tokens

API tokens authenticate requests to Telegraf Controller. 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 Telegraf Controller.

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 Telegraf Controller, define the INFLUX_TOKEN environment variable:

export INFLUX_TOKEN=
YOUR_TC_API_TOKEN

telegraf \
  --config "http://telegraf_controller.example.com/api/configs/xxxxxx/toml

Replace YOUR_TC_API_TOKEN with your Telegraf Controller API token.

For heartbeat requests

Telegraf uses the Heartbeat output plugin to send heartbeats to Telegraf Controller. 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.

[[outputs.heartbeat]]
  url = "http://telegraf_controller.example.com/agents/heartbeat"
  instance_id = "&{agent_id}"
  interval = "1m"
  include = ["hostname", "statistics", "configs"]
  token = "${INFLUX_TOKEN}"

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, Telegraf Controller 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 Telegraf Controller:

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.