3.4 KiB
| title | description | menu | weight | related | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Authorization | Understand how authentication and authorization work in Telegraf Controller, including user roles, API tokens, and endpoint security. |
|
106 |
|
{{% product-name %}} uses session-based authentication for the web UI and token-based authentication for API and Telegraf agent requests. Both mechanisms work together to control who can access the system and what actions they can perform.
User roles
{{% product-name %}} enforces a four-tier role hierarchy. Each role inherits the permissions of the roles below it, and higher roles unlock additional administrative capabilities.
| Role | Description |
|---|---|
| Owner | Full system access. Manages users, tokens, and settings. Only one owner exists at a time. Created during initial setup. |
| Administrator | Full system access. Same capabilities as the owner except cannot transfer ownership. |
| Manager | Manages configurations, agents, labels, and reporting rules. Manages own API tokens. Cannot manage users or settings. |
| Viewer | Read-only access to configurations, agents, labels, and reporting rules. Cannot manage tokens, users, or settings. |
Only one owner can exist at a time. The owner account is created during initial setup and cannot be deleted. If you need to change the owner, the current owner must transfer ownership to another user.
[!Tip] To change the owner of your {{% product-name %}} instance, see Transfer ownership.
API tokens
API tokens authenticate programmatic API requests and Telegraf agent connections to {{% product-name %}}.
Each token is scoped to the user who created it. The token's effective permissions are restricted to the creating user's role---a token cannot exceed the permissions of its owner. If a user's role changes to a role with less permissions, all of that user's existing tokens are automatically updated with restricted permissions or revoked to match the new role.
Tokens use the tc-apiv1_ prefix, making them easy to identify in configuration
files and scripts.
[!Important] A token value is shown only once at the time of creation. Store it in a secure location immediately---you cannot retrieve it later.
Endpoint authentication
By default, {{% product-name %}} requires authentication for API endpoints. Administrators can selectively require authentication for individual endpoint groups:
- Agents --- agent management endpoints
- Configs --- configuration management endpoints
- Labels --- label management endpoints
- Reporting rules --- reporting rule management endpoints
- Heartbeat --- agent heartbeat endpoints
When authentication is enabled for an endpoint group, every request to that group must include a valid API token or an active session.
[!Note] To configure which endpoint groups require authentication, see Manage settings.