Krafter Feature Flags

Ship features safely with instant rollouts, targeted rules, and built-in A/B testing. Evaluate from your server with a platform API key, or from a browser or mobile app with a client key that is safe to ship in a bundle.

Features

• Boolean, string, number & JSON flags — Typed values returned per evaluation; percentage rollouts and multi-value A/B tests are layered via rules and experiments
• Targeting rules — Conditional logic evaluated top-to-bottom per environment, with operators like equals, contains, in, and more
• Segments — Reusable user groups (e.g., "Pro Users", "Beta Testers") that can be referenced in any rule
• Experiments — Built-in A/B testing with variant allocation, conversion tracking, and results
• Projects & environments — Organize flags by project and evaluate per environment (development, staging, production)
• Client keys — A krf_client_ credential bound to one project and one environment, safe to ship in a browser bundle: it evaluates and tracks, and reads no definitions
• Webhooks — Real-time notifications when flags are created, toggled, or updated
• Audit log — Full history of every flag change with timestamp and actor

Quick links

• Quickstart — Create and evaluate your first flag in 5 minutes
• Rules & Targeting — Conditional rules, segments, and percentage rollouts
• Experiments — A/B testing with variants and conversion tracking
• API Reference — Full endpoint documentation
• Projects — Project management endpoints
• Client Keys — Evaluating from a browser or mobile app

Base URL

https://app.krafter.dev/api/v1

Management and server-side evaluation under /api/v1/flags/... require a Bearer token with flags:read or flags:write scope. See Quickstart for details. Requests are subject to platform rate limits — the evaluate, bootstrap, and track endpoints use the stricter strict bucket.

Browser and mobile callers use /api/v1/flags/client/... with a client key instead. Those endpoints have their own limits and never require a platform key.

Authentication and per-project permissions

Two kinds of credential reach this service.

Client keys (krf_client_) carry their own authorisation in the key itself: one project, one environment, evaluation and event tracking only. There is no scope to configure and no way to widen one. See Client Keys.

Platform API keys (kr_live_) are authorised at two layers:

1. Scope — flags:read or flags:write, checked first by KrafterWeb.Plugs.ApiKeyAuth.require_scope/2. A read-scope key on a write endpoint returns 401/403 before any business logic runs.
2. Per-resource permission — for flags, the resource type is flag_project, and the resource id is the project UUID. Enforced by KrafterWeb.Plugs.ResourcePermission on every endpoint that takes project_id directly, and by check_flag_project_permission/2 on every endpoint that takes flag_id (after the flag is loaded). When mismatched, both return 403 Forbidden.

Pass-through rule: a key with no flag_project permissions configured has unrestricted access to all projects in its team. Restrictions only kick in once you add at least one project permission to the key — at that point the key becomes scoped to the listed projects. Configure permissions in the dashboard under API Keys → Permissions when creating or editing the key, or via the Create Project flow if you provision keys programmatically.

Operational characteristics

• Evaluation cache. Flag rules are cached per (project_id, environment) for 60 seconds (Krafter.Flags.Cache, @ttl_seconds 60). Mutations (create / update / toggle / archive / delete) invalidate the project's cache entries and broadcast {:invalidate_cache, project_id} on PubSub topic "flags:cache", so other nodes flush in lockstep.
• Rate limit on hot paths. POST /flags/evaluate, GET /flags/bootstrap, and POST /flags/track go through the :strict_rate_limit pipeline (30 requests / 60 seconds per team, shared by every key of the team). High-traffic clients should call /bootstrap once per session and cache results in-process rather than re-evaluating on every page view. The /flags/client/... endpoints are limited separately — per IP and per client key, not per team — so browser traffic and server traffic cannot starve each other.
• Evaluation is metered the same from anywhere. One evaluate or bootstrap call charges one flags/evaluations unit per flag in the project, whether it came from your server with a platform key or from a browser with a client key, and both spend the same monthly quota.
• Evaluation analytics. Each evaluation increments an in-memory ETS counter via Krafter.Flags.Cache.record_evaluation/3. Counters are flushed to Postgres every minute by the FlagEvaluationAggregator Oban worker (config/config.exs, "* * * * *"). Analytics endpoints bucket by (date, hour), so newly-flushed counts can take up to a minute to appear in /flags/:id/analytics.
• Webhook deliveries. Outbound calls are signed with HMAC-SHA256, retried up to 5 times by Oban, and the webhook is auto-disabled (enabled = false) after 10 consecutive failures. See Webhooks and Webhook delivery for full headers, payload shape, and verification snippets.

MCP tools

The Flags service exposes 5 read-only MCP tools (scope flags:read): flags_list_projects, flags_list_flags, flags_get_flag, flags_list_audit_log, and flags_list_experiments. They share the same Bearer-token API key, rate-limit bucket, and audit log as the REST API. See the MCP tools reference for input schemas and the JSON-RPC envelope.