Any language (HTTP)
No Swift, Kotlin, Python or Go SDK, on purpose. The client tier is two HTTP endpoints. Any language that can POST can use it, and a working client is about thirty lines.
POST /v1/client/state a context in, its evaluated values out
GET /v1/client/stream server-sent events when those values change
Authenticate with a client (fk_clt_…) or mobile (fk_mob_…) key in Authorization: Bearer.
Get values
curl -X POST https://flags.acme.com/v1/client/state \
-H "Authorization: Bearer $FEATUREKIT_CLIENT_KEY" \
-H "Content-Type: application/json" \
-d '{ "context": { "key": "u-ana", "plan": "free" }, "seq": 1 }'
{
"contextHash": "3f9a0c1d7e2b4a6f9c8d1e0f2a3b4c5d",
"seq": 1,
"version": 412,
"connectionId": "c_8Xk2pQ9vR4mL7nW1",
"values": {
"new-checkout": { "value": false, "variationIndex": 0, "reason": "FALLTHROUGH" },
"loyalty-discount": { "value": 0, "variationIndex": 0, "reason": "FALLTHROUGH" },
"promo-banner": { "value": "Upgrade to Pro and save 10%.", "variationIndex": 1, "reason": "RULE_MATCH" }
}
}
values is everything you get: no rules, no percentages, not even which rule matched. An empty
connectionId means the node can't take another stream right now, so poll instead.
A minimal client
import json, urllib.request
def state(base, key, context, seq):
body = json.dumps({"context": context, "seq": seq}).encode()
request = urllib.request.Request(
f"{base}/v1/client/state",
data=body,
headers={"authorization": f"Bearer {key}", "content-type": "application/json"},
)
with urllib.request.urlopen(request) as response:
return json.load(response)
values = state("https://flags.acme.com", CLIENT_KEY, {"key": "u-ana", "plan": "free"}, 1)["values"]
def get(flag, default):
found = values.get(flag)
if found is None:
return default
# A wrong-typed value must never reach the caller in place of its default.
return found["value"] if isinstance(found["value"], type(default)) else default
Re-POST on an interval and you have a correct client, a poll interval behind instead of a second. That's the right trade for a CLI, a cron job or a background worker. Add the stream when you want live updates.
Stream changes
GET /v1/client/stream?connection=c_8Xk2pQ9vR4mL7nW1
Authorization: Bearer fk_clt_…
Accept: text/event-stream
event: ready
data: {"version":412}
event: values
data: {"version":413,"values":{"new-checkout":{"value":true,"variationIndex":1,"reason":"RULE_MATCH"}}}
valuesis a delta: merge it into what you hold, don't replace.409 UNKNOWN_CONNECTIONmeans the handle expired (15 idle minutes, or a restart). POST state again.- When the stream ends for any reason, POST state again and reopen. Wait about 1.5 seconds, with jitter.
- The key can go in a
keyquery parameter for clients that can't set headers, but a key in a URL ends up in logs.
Two ordering rules
Get these wrong and one user sees another user's flags.
- When the user changes, drop what you hold before you ask. Until the new answer arrives, return your defaults, not the previous user's values.
- Apply responses in the order you sent them. Send an increasing
seqand drop any response with a lowerseqthan the last one you applied. Also drop responses for a context key you're no longer on. Both checks, not either.
POST state {key: "user_A", seq: 1} slow
POST state {key: "user_B", seq: 2} fast, applied
seq 1 arrives late: drop it
Errors
| Status | error | Do |
|---|---|---|
| 400 | MISSING_CONTEXT, CONTEXT_* | Fix the context. Limits: 60 attributes, 1,024-character strings, 100-item arrays, 5 levels deep. |
| 401 | MISSING_SDK_KEY, UNKNOWN_KEY, KEY_REVOKED, WRONG_TIER | Check the key, and that it's a client or mobile key. |
| 401 | SIGNATURE_MISSING, SIGNATURE_INVALID | Serve your defaults. Don't retry unsigned. |
| 401 | SIGNATURE_EXPIRED | Keep serving what you hold, get a fresh signature, retry. |
| 429 | RATE_LIMITED | Wait Retry-After seconds. |
Every failure should end at your caller's default, never at null or an exception.
Signing in production
Production environments need the context signed by your backend:
signature = hex(HMAC_SHA256(secret, "{key}:{expiresAt}:{attributesHash}"))
attributesHash = first 32 hex characters of SHA-256 of the context as canonical JSON
(object keys sorted at every level, no whitespace)
Send signature and the same expiresAt (epoch seconds) with the context. See secure mode.
Every field and status is in the client tier reference.