Authentication

API keys

All REST endpoints authenticate with an API key in the x-api-key header:

curl https://api.reaktly.com/ingest \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ ... }'

Keys are created in the dashboard under Settings → API keys. The secret is shown once at creation — store it in your secret manager or environment, never in code. The dashboard keeps a prefix (e.g. rk_live_abc…) so you can tell keys apart later.

Scopes

A key can only do what its scopes allow — grant the minimum you need:

An endpoint returns 403 when the key is valid but lacks the required scope.

Rotating a key

1. Create the replacement key with the same scopes.
2. Deploy the new value to your integration.
3. Verify traffic, then deactivate the old key in the dashboard.

Keys can carry an expiry date; set one for keys used by contractors or temporary migrations.

Security best practices

• Store keys in environment variables or a secret manager — never in code, git, or client-side JavaScript.
• One key per integration — a leaked key then has a small blast radius and a clear owner.
• Use the minimum scopes — an ingestion key does not need usage:read.
• Set expiration dates where possible, and rotate on a schedule.
• Never put an API key in a website — browsers and mobile apps cannot keep secrets. The widget uses the public operator key instead.

Errors