Keys & Credentials
Quonfig has three kinds of credential: SDK keys, API keys (personal or
service-account), and your qfg login session. They are not interchangeable.
If you just want your app to read flags and configs, you want an SDK key. That's the only credential most applications ever need. The rest of this page is the canonical reference for all three, so you can read it once and never reach for the wrong one.
The mental model
Quonfig has two planes. The data plane (the delivery API) hands evaluated
config to your running application — it is on the hot path, and an SDK key
authenticates to it. The control plane (the Quonfig app) is where you manage
config — create flags, edit rules, push changes — and you authenticate to it,
either interactively with qfg login or programmatically with an API key.
In one line: SDK keys read; you (or your CI) write.
Identity lives on the control plane and is deliberately kept off the data plane. That same decision is why Personal Overrides have to carry your identity into the data plane as context: the SDK key won't carry it for you.
Which one do I use?
| I want to… | Use |
|---|---|
| Read flags/config from my server app | Backend SDK key (qf_sk_…) |
| Read flags from my browser / mobile app | Frontend SDK key (qf_pk_…) |
| Manage config from my laptop (CLI) | qfg login |
| Manage config from shared CI or an integration | Service-account key (qf_sa_…) |
| Manage config from my own script | Personal API key (qf_uk_…) |
| Resolve config into env vars at build/deploy time | qfg run with a backend SDK key, qfg login, or (in CI) an API key plus --environment |
| Override a flag just for me in local dev | An SDK key and qfg login — see Personal Overrides |
The credentials in detail
SDK keys — your app reading config
SDK keys are what your running application uses to fetch config from
the delivery API. They resolve to a single {workspace, environment} pair and
carry no user identity — they say which config to serve, never who is
asking. Because there's nothing personal in them, a development SDK key is meant
to be shared across your team; you don't create one per developer. There are
two flavors:
- Backend SDK key (
qf_sk_…, secret) — for server-side SDKs (Node, Go, Python, Ruby, Java, .NET). The SDK downloads the full config envelope and evaluates in-process, so it can see your raw targeting rules. Never ship it to a browser. - Frontend SDK key (
qf_pk_…, public) — for browser, React, React Native, and other client SDKs. Safe to ship in client bundles because evaluation happens server-side by the delivery API — the browser only ever receives evaluated values, never raw rules, and only configs marked "send to frontend SDKs."
Create SDK keys on the Environments & Keys page in the app (the
Environments & SDK keys tab), or with qfg sdk-key create. Each key is shown
once, when you create it.
See Backend SDKs and Frontend SDKs for how each one fetches and evaluates.
API keys — automation managing config
An API key gives a non-interactive process programmatic access to the control plane, so it can do what you could do by hand — list flags, edit config, push changes, generate types. Both kinds use Bearer auth and are scoped to one workspace. They differ in who the changes are attributed to:
- Personal API key (
qf_uk_…) is you, as a credential: changes show up under your name. Use it for your own scripts. Create it on the Environments & Keys page, CLI & API keys tab. - Service-account key (
qf_sa_…) acts as a named bot with its own role, so the audit trail shows the bot (for exampledeploy-bot) rather than a person. Use it for anything shared: CI, integrations, agents. An org admin creates it under Settings → Service accounts (the tab appears only for admins). With the CLI, setQUONFIG_WORKSPACEto the workspace's UUID, notorg/workspace; see the CLI environment variables reference.
Reach for an API key only when there's no human at a browser to complete an
OAuth flow: a CI job running qfg generate, a deploy step running
qfg run, a migration script. It does not
authenticate to the delivery API, so you can't use it to read config from an SDK.
REST API authentication has the step-by-step
for minting both kinds.
qfg login — you, at your desk
qfg login is the interactive, human equivalent of an API key. It runs a
device-code OAuth flow in your browser and stores the resulting token
locally. Every management command from the CLI — qfg list, qfg push,
qfg set-default, qfg override — rides on it. Use qfg login at your desk;
use an API key in automation.
Local dev: one shared SDK key + your own qfg login
The intended setup is simpler than you might expect. Your team shares one
development SDK key — you do not make a personal one per developer. An SDK
key carries no identity, so there's nothing personal in it to separate; a single
development key (kept in your team's .env.example, say) is the norm.
What makes local dev yours is qfg login, not a personal key. Logging in
identifies you to the control plane — that's how you manage config and how your
personal overrides resolve to
your values: your identity rides in as evaluation context while the shared SDK
key just says which environment to read. So day to day you hold two credentials
at once — the shared SDK key (your app reads config) and your own qfg login
(you manage config and see your own overrides).
Reference & anti-patterns
The full reference, for quick lookup and for agents wiring up an integration.
| Credential | Looks like | Conventional env var | Auth scheme | Talks to | Identity? |
|---|---|---|---|---|---|
| Backend SDK key | qf_sk_… | QUONFIG_BACKEND_SDK_KEY | HTTP Basic (1:<key>) | Delivery API (reads) | No — workspace + environment |
| Frontend SDK key | qf_pk_… | QUONFIG_FRONTEND_SDK_KEY (behind a framework prefix: NEXT_PUBLIC_, VITE_, REACT_APP_) | HTTP Basic (1:<key>) | Delivery API (reads, evaluated server-side) | No — workspace + environment |
| Personal API key | qf_uk_… | QUONFIG_API_KEY (pair with QUONFIG_WORKSPACE) | Bearer | Quonfig app (manage) | Yes — acts as you |
| Service-account key | qf_sa_… | QUONFIG_API_KEY (pair with QUONFIG_WORKSPACE=<workspace UUID>) | Bearer | Quonfig app (manage) | Yes — acts as a named bot |
qfg login | a stored token, not a string you paste | — (stored under ~/.quonfig/) | JWT | Quonfig app (manage) | Yes — acts as you |
Don't:
- Don't put a backend key (
qf_sk_…) in browser or client code — it can read your raw rules. Use a frontend key (qf_pk_…). - Don't use an API key (
qf_uk_…orqf_sa_…) to read flags from your app — it doesn't authenticate to the delivery API. Use an SDK key. - Don't use an SDK key to manage config — it can't reach the control plane.
- Don't commit real keys. SDK keys are shown once at creation; rotate freely by making new ones.