API keys

An API key (token) authenticates scripts, services, background workers, and the Telmoni CLI to the Telmoni API. API keys belong to a Project and are managed from the project's API keys page (/{organization}/{project}/api-keys).

Creating a keyCopy Anchor Link

Project Owners and Admins can mint, rotate, and revoke API keys.

1. Navigate to your project's API keys page.
2. Select Mint key, which opens the form over the page, as New project opens.
3. Provide a name describing what service uses the key (up to 100 characters), and optionally a description (up to 500).
4. Choose what it opens: Send spans, the ingest scope, which opens /otlp/v1/traces; Read the API, the read scope, which opens /v1; or both. Both are on to start; a key needs at least one. A key baked into an agent's process should send alone, so a leak of it reads nothing.
5. Choose when it expires: 30 days, 90 days (the default), 1 year, or Never (not recommended).

Where the api_tokens feature flag is off, for the deployment or for the organization, minting and rotating are refused with "API keys are switched off right now."; revoking always works. The console lets each person mint 5 keys, rotate 10 and revoke 20 a minute.

The raw token is displayed exactly once upon creation. Copy and store it in your secret manager immediately. Telmoni stores only a SHA-256 hash of the token; the plaintext appears in the mint or rotate answer alone.

Every key begins with the prefix telmoni_.

Using a keyCopy Anchor Link

Include the key as a bearer token in the HTTP Authorization header:

$ curl -H "Authorization: Bearer $TELMONI_API_KEY" https://api.telmoni.com/v1/organization

Each lane needs its scope: /v1 the read scope, and /otlp/v1/traces, where spans are sent, the ingest scope. A live key without the scope a lane needs is refused with 403 /errors/authz/forbidden.

The Telmoni CLI uses it from the TELMONI_API_KEY environment variable, for each command and without saving it, asking first at a terminal, or saves it with telmoni login --with-key, which reads it from standard input:

$ telmoni status          # with TELMONI_API_KEY set to a key holding read
$ telmoni login --with-key < key.txt

The client SDKs send spans to ingest with a key holding the ingest scope, from their configuration or TELMONI_API_KEY:

import { Telmoni } from 'telmoni';

const client = new Telmoni({ apiKey: process.env.TELMONI_API_KEY });

A key is minted in a project, is deleted with it, and follows it if the project is transferred to another organization. On /v1 it reads its project's organization (GET /v1/organization) and its project's roster (GET /v1/members), never the organization's whole roster: a key reads no more than the project Admin who minted it can see. A key remains active regardless of whether the individual user who created it leaves the project.

Who can see keysCopy Anchor Link

Anyone on the project (Owner, Admin, or Member) can view the list of active keys: each key's name, what it opens, creation date, last-used date (written at most once a minute, so a busy key is not a write per request), and expiration date. The secret itself is never visible after creation.

Rotating a keyCopy Anchor Link

To replace a key while the old one keeps working for a day, select Rotate on its row on the API keys page.

Rotating a key produces a new telmoni_ token (shown once) and keeps the previous token valid for a 24-hour grace period, or until its own expiry if that comes sooner. Both tokens authenticate during that window; after it, the old one is refused like a revoked key. The replacement keeps the key's name, description and scopes, is recorded as minted by whoever rotated it, and expires 90 days after rotation, whatever the old key's expiry was.

Minting, rotating and revoking a key are each recorded in the project's audit log.

Revoking a keyCopy Anchor Link

To immediately terminate a compromised or decommissioned key, select Revoke on its row. Revocation takes effect immediately: subsequent requests using that token fail with 401 Unauthorized. The record of a revoked or expired key is deleted seven days later by the retention sweep.

Key security best practicesCopy Anchor Link

• Isolate by workload: Create distinct API keys for each service or automation rather than sharing a single key across multiple tasks.
• Rotate with grace windows: Rotate rather than revoke a key in use: the old key keeps authenticating for up to 24 hours while you deploy the new one.
• Server-side only: Keep API keys in environment variables or secure vault systems on servers. Never embed API keys into client-side code, frontend browsers, or mobile applications.