Authentication and API keys

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, add only the required scopes, and choose how long the key should remain valid. Never is the default; fixed choices from one day through one year create a short-lived key whose expiry is shown with its metadata. Expiry cannot be extended after creation, so replace the key if a workload needs more time. The key is shown once.

The account API accepts the same optional expiry as an RFC3339 timestamp:

{
  "name": "One-day CI key",
  "scopes": ["traces:read"],
  "expires_at": "2026-08-04T12:00:00Z"
}

Omit expires_at for a key that never expires. A supplied timestamp must be in the future and no more than 365 days from creation. An expired key is rejected on its next use; revocation remains immediate and permanent.

Anectico keys begin with an_. Treat the rest as opaque; do not parse meaning from it.

Send an API key

The public REST API accepts:

X-Anectico-API-Key: an_...

It also accepts the generic X-API-Key header and Authorization: ApiKey an_.... MCP clients normally use:

Authorization: Bearer an_...

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
List the organization’s API keys	api_key:read
Create, rename, revoke, or re-scope API keys	api_key:write

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 Read & ingest preset includes every available read scope plus ingest:write and analytics:write. The narrower Ingest only preset covers OTLP and error ingestion; it does not authorize identity/events or replay. Full access is derived from the complete server scope catalog; for automatic quality checks it includes both evals:read and evals:write, so a key can read the configuration it is allowed to change.

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 may omit a query-string project_id or repeat its exact signed project. A different non-empty value returns 403 permission_denied before product logic runs; Anectico never silently substitutes the signed project for an explicitly conflicting selection. Organization-level keys retain request-time project selection, and many REST reads accept project_id as a query parameter.

The project binding is fixed for the life of a key. To move a workload to another project, create a replacement key for that project, deploy it, verify traffic, and revoke the old key.

Scope edits, expiry, project changes, and revocation take effect on the next request because the API key’s authorization is resolved server-side for every request, whether it arrives as telemetry or as an API call; successful checks are not cached. If that authorization check is unavailable, API-key OTLP and Capture requests fail closed with a retryable service-unavailable response. Removing traces:read, logs:read, metrics:read, errors:read, search:read, persons:read, or groups:read immediately makes the corresponding Query API return 403; ingestion continues when ingest:write remains present.

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.