API keys and authentication

Telemetry API requests accept an anonymous trial key or a team API key. Keep keys private and use them only in trusted server-side code. The one exception is an ingest-only key, which can only send events and is safe to embed in a browser, mobile app, or CLI.

Start with an anonymous key

The homepage supplies an anon_… key inside the setup prompt. It supports event ingestion, SQL queries, and table metadata without an account. Queries are available for 24 hours after your first event; create an account within 7 days to retain your data. A trial with no events expires 7 days after creation.

Signup detects your trial in the same browser. If you changed browsers or lost the private claim link, choose Already have an anonymous API key?, paste your key, and click Find my data. Then register, or log in to an existing account and confirm the link at Keep my data. Your events remain in their workspace and the original key keeps working. An expired trial cannot be recovered.

Manage account keys

Create keys for named workloads, give them the minimum required scope, store them outside source control, and revoke them when the workload is retired.

Open Team Settings → API Keys to create or manage keys. The full value is a credential, so copy it into the target secret manager rather than a shared document or issue.

Choose the narrowest scope

Telemetry supports three scopes:

An application that only emits events needs ingest. A reporting job needs read. Only read-and-write keys can delete data, change retention or partitioning, drop tables, or create and change dashboards and alerts, so never ship one in a browser, mobile application, public repository, or user-authored script. Keys created as "Write only" before October 2026 are now ingest keys.

Send the key

HTTP endpoints accept the key as the raw Authorization value or as a bearer token:

curl https://api.telemetry.sh/tables \
  -H "Authorization: Bearer $TELEMETRY_API_KEY"

SDK initialization accepts the same API key. For server-side code, use an environment variable or secret-manager lookup:

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

Never expose an anonymous trial, read, or read-and-write key through a public build-time prefix such as NEXT_PUBLIC_ or client configuration. A client that only sends events can use an ingest key instead. Create it with Ingest only scope in Team Settings → API Keys and confirm its scope before including it in a public build.

An ingest-only key cannot query the events it sends or manage your workspace. Verify an application's events in the Telemetry dashboard, or use a separate read key in a trusted server-side script. Keep that read key out of the client. Log only the fields you intend to send; a write-only key does not make private payloads safe to collect.

Separate keys by workload

Use distinct keys for production ingestion, staging, scheduled reporting, and coding-agent setup. Workload-specific keys make rotation and incident response smaller: revoking one reporting key should not interrupt event ingestion.

Name the key after its owner and purpose. Record where the key is deployed, its scope, and the expected rotation owner without recording the key value itself.

Rotate and revoke safely

Create a replacement key first, deploy it to the workload, verify successful requests, and then revoke the previous key. Exercise both ingestion and query paths when rotating a read-and-write key.

If a private key appears in a commit, log, screenshot, prompt, or public client bundle, treat it as compromised. Revoke it immediately, replace it, and review the affected team tables and query activity. An ingest key intentionally embedded in a public client remains write-only, but anyone who copies it can send events. Revoke and replace it if it is being misused.

Continue with the Log API, Query API, and sensitive-data guidance.