Star
SDKs

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"}}}
  • values is a delta: merge it into what you hold, don't replace.
  • 409 UNKNOWN_CONNECTION means 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 key query 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.

  1. 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.
  2. Apply responses in the order you sent them. Send an increasing seq and drop any response with a lower seq than 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

StatuserrorDo
400MISSING_CONTEXT, CONTEXT_*Fix the context. Limits: 60 attributes, 1,024-character strings, 100-item arrays, 5 levels deep.
401MISSING_SDK_KEY, UNKNOWN_KEY, KEY_REVOKED, WRONG_TIERCheck the key, and that it's a client or mobile key.
401SIGNATURE_MISSING, SIGNATURE_INVALIDServe your defaults. Don't retry unsigned.
401SIGNATURE_EXPIREDKeep serving what you hold, get a fresh signature, retry.
429RATE_LIMITEDWait 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.