Service accounts
Machine identities that hold the API tokens your CI pipelines, scripts, and coding agents use.
A service account is a machine identity in your organization. It holds one or more API tokens, the bearer credentials that authenticate the Telflo API and the Telflo CLI from scripts, CI pipelines, and other tools outside the Telflo UI. Anything a token creates through the API belongs to the service account, so activity stays attributable to the integration rather than to a person, and a token can be rotated by adding a new one and deleting the old without changing who the API acts as.
Service accounts are managed in Settings > Service Accounts by organization admins. The section opens with an About service accounts introduction and a link to the interactive API reference. API tokens are separate from the install and fleet tokens that authenticate a fleet's collectors; see Tokens & security.
Create a service account
- Go to Settings > Service Accounts and select Create service account.
- Enter a Name that says what uses the account, such as
CI pipeline, and select Create.
Names are unique among the organization's current service accounts; a deleted account's name can be used again. The new account joins the organization as a member with the Contributor role and an email address ending in @telflo.invalid. It appears in the Active list under Permissions like any member and counts toward the organization's member limit. See Members & roles.
The service account list
| Column | Contents |
|---|---|
| Name | The account's name. Select it to open the account. |
| Created | When the account was created. |
| Created by | The admin who created it. |
| Tokens | How many tokens the account holds that have not been deleted; expired tokens are counted. |
The delete icon at the end of a row opens the deletion dialog described below. An organization with no accounts shows No service accounts yet.
Tokens created in the earlier API Tokens section, before service accounts existed, now belong to service accounts created for them, one per token and named after it. Those accounts keep their earlier email addresses and work like any other.
Add a token
Open a service account by selecting its name. The page shows the account's email address, Created, Created by, and Tokens, with a Rename button, above an API Tokens table.
- Select Create token.
- In the Create API token dialog, enter a Name for the token, such as the job or environment it is for. Token names are unique within the account, and a deleted token keeps its name; give a replacement token a new name.
- 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, optional). Left empty, the token does not expire.
- Select Create token. The Copy your token dialog shows the token value; copy it and store it as a secret, then select Done.
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 under a new name.
| 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 & Write or Read. |
| Expires | The expiry date, or Never. |
| Last used | When the token last authenticated a request, or Never. |
| Created | When the token was created. |
Every token value starts with tf_, and the prefix is its first 11 characters. Telflo stores a hash of the token value and the displayed prefix, not the token itself.
An organization admin can also add a token to a service account while signing in to the CLI, with Use a CI token instead on the Authorize Telflo CLI page. See CLI overview.
Delete a token
Select the delete icon on a token's row, then Delete in the Delete token dialog. Any client using the token loses access on its next request, and deletion cannot be undone. A token also stops authenticating when it expires, and when its service account is deleted or removed from the organization.
Rename a service account
Select Rename on the account's page, change the Name in the Rename service account dialog, and select Save. The account's tokens are unaffected.
Delete a service account
Select the delete icon on the account's row in the list. The Delete service account dialog states what happens: the account's tokens stop working immediately, the account is removed from the organization, and any secrets, variables, share links, uploaded files, chat history, account settings, and collectors it registered are permanently deleted. Configurations, configuration versions, validation pipelines and rules, and test definitions and runs the account created are kept, still attributed to it. Type the account's name to confirm and select Permanently delete. Deletion cannot be undone, the account cannot be restored, and its name becomes available for a new account.
Removing the service account's member row under Permissions has the same effect on its tokens: they stop authenticating until an admin restores the member.
What a token can do
A token authenticates requests to the Telflo API's first version, as its organization only. It acts as its service account, a Contributor: it can read and write the configurations the service account created and the organization's published ones, but never another member's unpublished draft. Configurations created through the API are drafts owned by the service account until they are published.
| Action | Requires |
|---|---|
| Confirm the token and the organization it belongs to | Read |
| List configurations, read one with its versions, and read a version's YAML | Read |
| Validate collector YAML on a collector version | Read |
| Lint the OTTL expressions in a configuration | Read |
| Read a pipeline test's status, result, and output | Read |
| Read the validation rules saved on a version | Read |
| List fleets and their deploy groups | Read |
| Browse the public flows | Read |
| Create a configuration, locked to OpenTelemetry Collector Contrib | Write |
| Append a version, edit a draft version's YAML or collector version, or publish a version | Write |
| Rename a configuration or change its description | Write |
| Save validation rules on a version | Write |
| Start a pipeline test | Write |
| Create a server fleet or a Kubernetes supervisor fleet | Write |
| Create a deploy group, change its assignment, or produce its install command | Write |
The API currently offers one collector distribution, OpenTelemetry Collector Contrib: a request that names another distribution, such as ClickStack, is rejected. Configurations already locked to ClickStack keep reporting it and can still be read and tested through the API.
Requests are limited to 60 per minute for each token, and request bodies to 1 MB. For the endpoint list, limits, and error codes, see API endpoints.
Use a token
- From the CLI, set
TELFLO_API_TOKEN, or store the token withtelflo login --token. See CLI overview. A person working in the CLI needs no token:telflo loginsigns the CLI in as that person, and the API attributes their changes to them. - From any HTTP client, send the token as a bearer credential:
Authorization: Bearer tf_...Recommendations
- Create one service account per integration, such as a CI pipeline or a coding agent, so its work is attributed to it and can be cut off by deleting the account.
- Give each job or environment its own token, named accordingly, so one can be revoked 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 adding a replacement token and deleting the old one.
Last updated on