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, fleets, deployments, and pipeline tests from scripts, CI pipelines, and other tools outside the Telflo UI. The CLI authenticates with the same tokens.
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 and update resources; leave it off for a read-only token. Write access includes read access. The API has no delete operations.
- 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 stops being active in the organization, whether it is removed or set inactive. 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 covers:
| Action | Requires |
|---|---|
| Confirm the token and the organization it belongs to | Read |
| List configurations, and read one with its YAML and version history | Read |
| Read the validation rules saved on a version | Read |
| Validate collector YAML, and lint its OTTL expressions | Read |
| List flows and read a flow's YAML | Read |
| List fleets and their deployments | Read |
| Read a pipeline test run's status and output | Read |
| Create a configuration, append a version, and edit a draft version | Write |
| Publish a version, and save validation rules on it | Write |
| Create a fleet, create or update a deployment, and prepare an install command | Write |
| Start a pipeline test run | Write |
Starting a pipeline test run requires write access, because the run is recorded against the configuration.
A token reads the organization's published configurations; another member's unpublished draft is not visible to it, and a draft the token itself creates is not visible to your members until it is published. The YAML returned for a configuration is its latest saved version, which can be newer than the published version.
Requests are limited to 60 per minute for each token; over the limit the API answers 429 with a Retry-After header. Request bodies are limited to 1 MB, rejected with 413. A test run's input sample is limited to 1 MB separately.
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