Secure mode
Client keys are public, so without a check anyone could ask "what flags does the CEO's account get?". Secure mode has your backend sign each user's context, and featurekit refuses contexts it didn't sign.
It's required in every environment marked isProduction, and optional elsewhere. The server SDK
doesn't need it: a server key is already secret.
Set it up
-
Give the control plane a secret control plane
SECURE_MODE_SECRET=$(openssl rand -hex 32)At least 32 characters. Without it, a production environment refuses every client request with
SECURE_MODE_UNCONFIGUREDrather than serving unsigned contexts. -
Sign contexts in your backend your backend Where the session is already trusted.
featurekit-server/secure-modeloads onlynode:crypto.import { signContext, contextHash } from "featurekit-server/secure-mode"; app.get("/api/flags-signature", requireSession, (req, res) => { const context = { key: req.user.id, plan: req.user.plan }; const expiresAt = Math.floor(Date.now() / 1000) + 3600; res.json({ context, expiresAt, signature: signContext(context.key, expiresAt, SECRETS, contextHash(context)), }); });SECRETSis the same value asSECURE_MODE_SECRET, split on commas. -
Pass it to the client SDK browser
const { context, signature, expiresAt } = await (await fetch("/api/flags-signature")).json(); const flags = new FeaturekitClient({ clientKey: "fk_clt_…", baseUrl: "https://flags.acme.com", context, contextSignature: signature, contextSignatureExpiresAt: expiresAt, onSignatureExpiring: async () => { const fresh = await (await fetch("/api/flags-signature")).json(); return { signature: fresh.signature, expiresAt: fresh.expiresAt }; }, });
Sign the attributes, not just the key
Passing contextHash(context) covers every attribute. Without it, the signature only proves
who the user is, and they could send { key: "u-ana", plan: "enterprise" } with their own
valid signature and be evaluated as an enterprise customer.
Expiry
A signature lasts until expiresAt. A captured one can be replayed until then, which is why it
expires at all: a signature over the key alone would be a credential that never expires. The server refuses any
expiresAt further out than SECURE_MODE_MAX_TTL_SECONDS (24 hours by default) before
it even checks the signature. Refresh before expiry with onSignatureExpiring.
What the SDK does on each error
| Error | The client SDK… |
|---|---|
SIGNATURE_EXPIRED | Keeps serving the values it has and asks onSignatureExpiring for a fresh pair. Expiry isn't an identity change. |
SIGNATURE_INVALID, SIGNATURE_MISSING | Drops to your defaults. Never silently retries unsigned. |
SIGNATURE_TTL_TOO_LONG | Refused outright. Sign with a shorter lifetime. |
SECURE_MODE_UNCONFIGURED (500) | The server needs signatures but has no secret, and refuses rather than serving unsigned. Set SECURE_MODE_SECRET. |
Rotating the secret
Signing uses the first secret, verification tries all of them, so rotation is two ordinary deploys:
SECURE_MODE_SECRET=new,old, then deploy the control plane and your signers.- Once everything signs with the new one,
SECURE_MODE_SECRET=newand deploy again.
Rotating in one step invalidates every signature at once, and every browser drops to defaults until it signs again.
Other languages
signature = hex(HMAC_SHA256(secret, "{key}:{expiresAt}:{attributesHash}"))
attributesHash = first 32 hex characters of SHA-256 of the canonical context JSON
(object keys sorted at every level, no whitespace)
{"key":"u-ana","plan":"free","tenureMonths":2}
Opting an environment out
To allow unsigned contexts in a specific production environment, list its id in
UNSIGNED_CONTEXT_ENVIRONMENT_IDS. It's an explicit list so the exception is visible in your
configuration, not a default.