API Keys and Authentication
Telemetry API requests accept an anonymous trial key or a team API key. Keep both private and use them only in trusted server-side code.
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:
| Scope | Use it for |
|---|---|
read |
Queries, table discovery, schemas, and read-only reporting |
write |
Event ingestion and supported write operations |
read-and-write |
A trusted server or automation that must both send and query data |
An application that only emits events normally needs write. A reporting job normally needs read. Avoid giving a browser, mobile application, public repository, or user-authored script a team key.
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. Keep initialization in server-side code and use an environment variable or secret-manager lookup:
import telemetry from "telemetry-sh";
telemetry.init(process.env.TELEMETRY_API_KEY);
Do not use a public build-time prefix such as NEXT_PUBLIC_ or serialize the key into client configuration.
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 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.
Continue with the Log API, Query API, and sensitive-data guidance.