API tokens
Create organization-scoped tokens for the Telflo API.
An API token is a bearer credential for the Telflo API, scoped to the organization it is created in. Use API tokens to work with your organization's configurations from scripts, CI pipelines, and other tools outside the Telflo UI.
API tokens are managed in Settings > API Tokens by organization admins. They are separate from the install and fleet tokens that authenticate a fleet's collectors; see Tokens & security.
Create a token
- Go to Settings > API Tokens and select Create token.
- Enter a Name, such as the integration the token is for. Token names are unique within the organization, including deleted tokens.
- Select Allow write access for a token that can create, update, and delete resources; leave it off for a read-only token. Write access includes read access.
- Optionally set Expires in (days). Left empty, the token does not expire.
- Select Create token. The Copy your token dialog shows the token value; copy it now and store it as a secret.
The token value is shown once, at creation, and cannot be retrieved later. If it is lost, delete the token and create a new one.
The token list
The API Tokens section lists the organization's active tokens.
| Column | Contents |
|---|---|
| Name | The token's name. |
| Prefix | The first characters of the token value, to match a stored token to its entry. |
| Access | Read or Read & Write. |
| Expires | The expiry date, or Never. |
| Last used | When the token last authenticated a request, or Never. |
| Created | When the token was created. |
Telflo stores a hash of the token value and the displayed prefix, not the token itself.
Delete a token
Select the delete icon on a token's row and confirm. Deleting a token invalidates it: any client using it loses access on its next request. Deletion cannot be undone.
A token also stops authenticating when it expires, and when its service-account member is removed from the organization. It is not affected by the member who created it leaving the organization.
Service accounts
Each API token is backed by a service account that Telflo creates with it: a machine member with an email address ending in @telflo.invalid and the Contributor role. It appears in the Permissions area's Active member list like any member. See Members & roles.
- Removing the service-account member from the organization disables its token immediately; restoring the member re-enables it.
- Deleting a token does not remove its service account. Remove the member from Permissions once the token is gone.
What a token can do
A token authenticates requests to the Telflo API's first version, as its organization only. The API currently covers:
| Action | Requires |
|---|---|
| Confirm the token and the organization it belongs to | Read |
| List the organization's configurations | Read |
| Read a configuration, including its latest YAML | Read |
| Validate collector YAML against a collector version | Read |
A token reads the organization's published configurations; another member's unpublished draft is not visible to it. The YAML returned for a configuration is its latest saved version, which can be newer than the published version. Endpoints that create and change resources are not yet available. Requests are limited to 60 per minute for each token, and request bodies to 1 MB.
Recommendations
- Create one token per integration and name it accordingly, so a retired or compromised integration can be cut off by deleting its token without affecting the others.
- Use read-only tokens unless the integration must change resources.
- Set a bounded expiry for tokens in long-lived automation, and rotate by creating a replacement token and deleting the old one.
Last updated on