Security

Keys and scopes

Every key belongs to one environment of one project. There are four kinds:

• Server, CI and admin keys are secrets: never ship them in browser or mobile code.
• Keys cannot bypass review: an environment that requires approval can only be published from the dashboard through an approved change.
• The edge checks the key kind before anything else and answers 403 when a kind may not use an endpoint (see the endpoint matrix).

Client vs server keys

A client key is public by design. Anyone who has your page has the key and can read every client-exposed flag, including its rules, the segments those rules reference and the attribute values they compare against, and can send telemetry. Server-only flags, and segments that only server-only flags use, are never in the client view. Evaluation runs on the user's device, so the user can change the result. Therefore:

• Mark a flag client-exposed only if its rules may be public. Do not put customer lists, internal e-mail addresses or secrets into rules of client-exposed flags or into segments they reference.
• Never use a browser flag for authorization. Decide access on the server.
• Client keys may appear in request URLs (?key= on the event stream), and therefore in request logs.

Creating, rotating, revoking

• Admins create keys under Settings → SDK & access keys. The full key is shown once; NanoFlags stores only a SHA-256 hash and a short prefix, so it cannot be shown or recovered later.
• Rotate (client, server and CI keys): create a replacement of the same kind and environment, update your application, then revoke the previous key. The keys list shows when each key was last used.
• Revoke: the edge stops accepting the key within about a minute (validated keys are cached for up to 60 s). While NanoFlags' origin is unreachable, the edge keeps serving the last configuration to keys it validated in the last 24 hours, so a revoked key can keep receiving configuration for up to 24 hours in that situation.
• An open live socket is authenticated when it opens; after revocation it stops receiving new revisions when the SDK replaces it (about every 50 minutes) and at the latest after 2 hours.
• Revocation stops updates. It does not erase configuration that already reached a process: SDKs keep evaluating their last bundle.
• Key creation and revocation are recorded in the activity log and can trigger the key.lifecycle webhook.

Signing

Every published revision is signed with Ed25519 before distribution, with a separately signed client view for client keys. The edge serves the signed bytes unchanged. GET /v1/keys lists the public keys, each with a kid and a status (active or retiring), so a signing key can be rotated without breaking SDKs that still hold bundles signed with the previous one.

• From JavaScript SDK 0.4.0, and in the Python and Go SDKs from 0.1.0, the SDKs verify signatures by default when they read from the NanoFlags edge (https://edge.nanoflags.io) and reject unsigned bundles there. In JavaScript, verification needs Ed25519 in WebCrypto (Node.js 20+, current browsers); on other runtimes set verify: false.
• Any other client can verify bundles as described in Signatures. Pin the public key in your build if the edge itself is in your threat model; keys fetched from /v1/keys are only as trustworthy as the edge that served them.
• Test-session bundles are not signed, and a signature does not prove freshness.

Redaction defaults

• SDK telemetry sends no context values by default. A sampled event carries only the names of the context attributes the flag's rules reference, mapped to their types ({ "region": "string" }). Attributes no rule uses are dropped. Opt in to more with events.redact; disable telemetry with events: false. See Telemetry.
• Flag values are sent with sampled events. Do not put secrets in flag values.
• The SDK never persists the SDK key; a stored bundle is bound to the key and edge URL by a non-secret fingerprint.
• Code references (refs scan) upload the file path, line and that source line (up to 240 characters). They are opt-in.
• The edge never logs keys, key hashes or session tokens. Webhook and e-mail delivery logs contain ids, outcomes, status codes, the target host name and masked recipients, never secrets or full URLs.
• Webhook payloads never include before/after snapshots of a configuration.

Data retention

Roles and approvals

• Roles are enforced by the database, not only by the dashboard.
• In an environment that requires approval, a change needs approvals from the configured number (1 to 5) of admins or owners other than its author. An approval is bound to the exact draft it approved; any later edit makes it stale.
• Every publish names the revision it expects to replace, so a stale browser tab cannot overwrite a newer revision.
• Changes to flags, keys, environments, members and publications are recorded in the activity log with the actor and time.

Two-step verification

• Any member can add an authenticator app (TOTP) under Profile & security. Once an account has a verified authenticator, the dashboard requires the second step at sign-in before the product opens.
• Owners can turn on Require two-step verification for owners and admins (Settings → Organization). Owners and admins without an authenticator are then sent to set one up before they can use the product.