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, plus an optional request-rate figure:

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

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.

rate_limit is the key's expected request volume in requests per hour. It is optional; omit it or send 0 to record the platform default. A supplied value must be a whole number between 0 and 1000000 — negative values and values above that maximum return 400 invalid_request naming rate_limit, without creating a key. The figure is stored with the key and returned with its metadata; it does not on its own change how your requests are throttled, and plan limits apply regardless of what a key records.

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 evaluation 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.

A key created without a project selection is bound to the organization's default project. Creating an organization-level key is an explicit choice: send "org_wide": true in the create-key request (the CLI's anectico agent bootstrap --org-wide does this), and the key is minted with no project binding at all.

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.

That binding is also an authority floor when one API key creates another. A project-scoped key with api_key:write can create a successor only in its own project; requesting org_wide or naming a sibling project returns 403 forbidden. Omitting the project keeps the creator's project — it never widens the successor because the default project cannot be resolved.

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.