Reference
Authentication and API keys
Create, scope, send, rotate, and revoke Teml credentials safely.
Human dashboard sessions and programmatic API keys are separate credentials. Use API keys for SDKs, collectors, CI, CLI automation, and MCP clients.
Create a key
Open Settings → Access, create an API key, select a project when appropriate, and add only the required scopes. The key is shown once.
Teml keys begin with tm_. Treat the rest as opaque; do not parse meaning from it.
Send an API key
The public REST API accepts:
X-Teml-API-Key: tm_...It also accepts the generic X-API-Key header and Authorization: ApiKey tm_.... MCP clients
normally use:
Authorization: Bearer tm_...Use the header documented by the SDK or client you are configuring rather than sending multiple credential headers.
Common key recipes
Scopes use resource:action names.
| Purpose | Required starting scopes |
|---|---|
| OTLP traces, logs, metrics, and captured errors | ingest:write |
| SDK identity, group, and diagnostic events | analytics:write in addition to ingest:write |
| Browser session replay | replay:write |
| Evaluate feature flags and record exposures | flags:read plus analytics:write |
| Upload source maps, ProGuard mappings, or dSYM binaries | errors:write |
| Register a release in CI | releases:write |
| Read through MCP | mcp:read |
| Allow MCP writes | mcp:write plus domain-specific scopes |
| Search logs | logs:read |
| Read traces | traces:read |
| Read or triage Issues | errors:read or the required error write scope |
Most application SDK integrations therefore use a project-scoped custom key with ingest:write
and analytics:write. Add replay:write only to a browser key that records replay. The
Ingest only preset covers OTLP and error ingestion; it does not authorize identity/events or
replay.
Client-side feature flags are the narrow exception to the usual no-read-scope rule. A browser flag
key requires flags:read, which also makes the project’s flag configuration readable to that
client. Keep flag targeting and payloads free of secrets.
The Access screen is the current source for the complete scope catalog. See the permission scope reference for the selectable groups and safe key patterns.
Project scope
A project-scoped key cannot be widened by passing a different project_id. For organization-level
keys, many REST reads accept project_id as a query parameter.
Rotate and revoke
Create the replacement key, deploy it, confirm traffic uses it, then revoke the old key. Revoke immediately if a key is committed, logged, included in a screenshot, or exposed to an untrusted client.