Use pre-shared tokens

By default, Telegraf Controller generates a random value when you create an API token. A pre-shared token is a token whose raw value you supply yourself. Because Telegraf Controller stores a deterministic hash of the value, installing the same value on several instances gives you one credential for your whole fleet. Use pre-shared tokens for API clients, CI pipelines, and infrastructure-as-code modules that interact with more than one Telegraf Controller instance.

Each instance keeps its own description, permissions, expiration, and owner for the shared value. There is no synchronization between instances. This lets you grant different permissions per instance, for example, read-only access on production and read-write access on development. It also means the token metadata can drift between instances.

Provide a token value

Use either of the following as the token value:

• A value generated by another Telegraf Controller instance: create a token without supplying a value, copy the generated value, and then supply that value when creating tokens on your other instances.
• A value you generate yourself: see Generate a token value.

The value must meet the token requirements.

Use the UI

1. Navigate to the API Tokens page.
2. Click Create API Token.
3. Enter a Description for the token.
4. Expand Provide your own token string and enter the value in the Token String field.
5. (Optional) Set an Expiration date and Custom permissions as described in Create an API token.
6. Click Create.

Use the API

Include the optional rawToken field in a POST /api/tokens request:

curl -X POST https://telegraf-controller.example.com/api/tokens \
  -H "Authorization: Bearer 
ADMIN_API_TOKEN
" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "ci-pipeline",
        "permissions": "configs:read",
        "rawToken": "
SHARED_TOKEN_VALUE
"
      }'

Replace the following:

• ADMIN_API_TOKEN: an API token with permission to create tokens on the instance
• SHARED_TOKEN_VALUE: the token value to install, matching the token requirements

To install the same credential across a fleet, run the same request against each instance and vary the description, permissions, and expiration as needed.

Token requirements

A supplied token value must be the prefix tc-apiv1_ followed by exactly 64 lowercase hexadecimal characters (32 random bytes):

tc-apiv1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Values that don’t match this format are rejected with 400 Bad Request.

The format requirement protects the stored hash. Telegraf Controller stores only a SHA-256 hash of the value, and a 256-bit random value cannot be brute-forced or looked up in a rainbow table, while a short or human-chosen string could be.

Generate a token value

Use any of the following commands to generate a value that meets the token requirements:

printf 'tc-apiv1_%s\n' "$(openssl rand -hex 32)"

$bytes = [byte[]]::new(32)
[System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
"tc-apiv1_" + (($bytes | ForEach-Object { $_.ToString('x2') }) -join '')

python3 -c "import secrets; print('tc-apiv1_' + secrets.token_hex(32))"

Uniqueness and conflicts

A raw value maps to exactly one token per instance. You cannot register the same value twice under two descriptions. It is one credential, and two descriptions require two distinct values.

POST /api/tokens returns 409 Conflict with a machine-readable error code when a conflict occurs:

Correct a token’s permissions

Token permissions are fixed at creation. There is no endpoint that edits them. To correct a mistake, delete or revoke the token, and then create it again with the same value and the correct permissions. For a pre-shared token this is inexpensive because you still hold the value. Anything already using the value keeps working.

Disable pre-shared tokens

Pre-shared tokens are enabled by default. To make an instance refuse client-supplied token values, set the disable-preshared-tokens option at startup:

DISABLE_PRESHARED_TOKENS=true ./telegraf_controller

Or use the command flag:

./telegraf_controller --disable-preshared-tokens

When disabled:

• POST /api/tokens requests that include a rawToken field return 403 Forbidden with the error code preshared_tokens_disabled. Requests without the field keep working as before.
• The UI hides the Provide your own token string field. The UI learns the instance’s state from GET /api/tokens/capabilities, which returns { "preSharedTokensEnabled": boolean }.