Server API keys

A server API key authenticates your own backend to Spectry — the credential the Node.js SDK needs. Unlike the write key, it is a secret: it can read every flag definition for the site, so it must never reach a browser bundle, a mobile app, or anything else a user can inspect.

Creating a key

1. Go to Site settings → Security & API.
2. Under Server API keys, choose Create key.
3. Give it a name describing where it runs — "checkout-api", "nightly-worker". When you later need to revoke one, the name is how you know what you are about to break.
4. Pick its scopes, then copy the key.

The key is shown once. Only a SHA-256 hash is stored, so we cannot show it to you again or recover it. If you lose it, revoke it and create another.

Keys are prefixed by environment: sk_live_… in production and sk_test_… elsewhere. The dashboard lists only the prefix (for example sk_live_a1b2c3d4) so you can tell keys apart without exposing them.

Scopes

Grant the narrowest set that works. A key limited to writing events cannot read your flag configuration even if it leaks.

• config:read — read flag and experiment definitions, and evaluate them for a user. Needed by any app that calls isOn().
• events:write — send custom events and server-side conversions. Needed for logEvent().

The Node.js SDK uses both if you use both halves of it. A worker that only reports events needs events:write alone.

Restricting and expiring a key

• IP allowlist — optional. When set, the key only works from those addresses. Worth it for a key on fixed infrastructure; skip it on autoscaling platforms where egress IPs move, or the key will fail unpredictably.
• Expiry — optional. An expired key is refused; the SDK logs it once and keeps serving its last known configuration rather than failing your requests.

Rotating

Because keys are independent, rotation needs no downtime:

1. Create a second key with the same scopes.
2. Deploy it to your servers.
3. Confirm traffic is flowing, then revoke the old one.

Revoking takes effect within a minute. Do it immediately if a key may have been exposed — revoking one key never affects the others, or the browser snippet.

Storing keys

Keep the key in an environment variable or your platform's secret manager, never in source control or a client bundle. If a key ever appears in a URL, treat it as compromised and revoke it: query strings end up in access logs, proxy logs and Referer headers. Spectry refuses any request that carries a key in the query string rather than honouring it.