---
title: Use API tokens
description: Use API tokens to authenticate Telegraf agents, heartbeat requests, and external API clients with Telegraf Controller.
url: https://docs.influxdata.com/telegraf/controller/tokens/use/
estimated_tokens: 1068
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/tokens/use/
date: '2026-10-06T09:35:17-06:00'
lastmod: '2026-10-06T09:35:17-06:00'
---

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 TELEGRAF\_CONTROLLER\_TOKEN environment variable

When retrieving a configuration from a URL, Telegraf only sends an`Authorization` header when it detects an authentication environment variable.
To authorize Telegraf to retrieve a configuration from Telegraf Controller,
define the `TELEGRAF_CONTROLLER_TOKEN` environment variable before starting
Telegraf:

```bash
export TELEGRAF_CONTROLLER_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.

When `TELEGRAF_CONTROLLER_TOKEN` is set, Telegraf sends the token in the`Authorization` header using the `Bearer` scheme. The Telegraf config watcher
(enabled with `--config-url-watch-interval`) uses the same environment variable
to authorize its periodic update checks.

> [!Note]
> #### Using Telegraf 1.38.x or earlier?
>
> Telegraf 1.39+ is required to read `TELEGRAF_CONTROLLER_TOKEN`. On earlier
> versions, use the `INFLUX_TOKEN` environment variable instead. Telegraf sends`INFLUX_TOKEN` in the `Authorization` header using the `Token` scheme.
> Telegraf Controller accepts tokens sent with either scheme, so you can
> upgrade Telegraf at your own pace.
>
> If both environment variables are set on Telegraf 1.39+,`TELEGRAF_CONTROLLER_TOKEN` takes precedence.

### For heartbeat requests

Telegraf uses the [Heartbeat output plugin](/telegraf/v1/output-plugins/heartbeat/)to send heartbeats to Telegraf Controller.
Use the `TELEGRAF_CONTROLLER_TOKEN` environment variable to define the `token`option in your heartbeat plugin configuration.
Telegraf uses the environment variable value defined when starting Telegraf.

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

When authentication is required for the heartbeat endpoint, agents must include
a valid token with each heartbeat request.
The token must have **write** permission on the **Heartbeat** resource, and
the user who owns the token must be active.
Telegraf Controller rejects a heartbeat request, and doesn’t update the
agent’s status, when the request is missing a token, the token is invalid or
expired, or the token lacks Heartbeat write permission.
If heartbeats are rejected with `Invalid token` even though the same token
works in the web interface and the API, see[Agent heartbeats return 401 Invalid token](/telegraf/controller/admin/troubleshoot/agents/#agent-heartbeats-return-401-invalid-token).
If heartbeats are rejected with `Insufficient permissions`, see[Agent heartbeats return 403 Insufficient permissions](/telegraf/controller/admin/troubleshoot/agents/#agent-heartbeats-return-403-insufficient-permissions).

## 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.

For more information about using the API, including how to explore the
interactive API reference, see the[Telegraf Controller API](/telegraf/controller/reference/api/).

> [!Note]
> If authentication is disabled for an endpoint, requests to those endpoints do not require a token.
> See [Endpoint authentication](/telegraf/controller/reference/authentication-authorization/#endpoint-authentication)for details on configuring authentication requirements per endpoint.

#### Related

* [Authentication and authorization](/telegraf/controller/reference/authentication-authorization/)