Access: flags and keys¶
Two things decide whether a call to the Questions Framework works:
- Feature flags. Each QF feature is off for a brain until a platform admin turns it on.
- Who is calling. A person signed in to the web app is checked by their role. An API key is checked by its scopes, and for some acts by its role too.
Feature flags¶
All QF flags are off by default. Only a platform admin can turn a flag on. Tenant users, Admins included, can't see or change flags.
| Flag | Needs | What it turns on |
|---|---|---|
question_store_db |
The Questions Framework in the database: Questions and Answer Keys are indexed from the brain's store, and eval runs and results are kept. Gates submitting answers, grading, standing, the eval run list and judge agreement, for people and keys alike. Everything else below needs it. | |
qf_developer_api |
question_store_db |
API keys on the rest of the developer API and on the remote QF MCP endpoint (/v1/mcp/questions). Without it a key can still use the routes question_store_db gates, and nothing else. A signed-in person isn't affected by this flag. |
question_catalog |
Listing, reading and matching published Questions. A key also needs question_store_db and qf_developer_api. |
|
questions_workspace |
question_store_db |
The Questions dashboard in the web app. Also: certification sign-off and certification status (without it a certification is trusted without sign-off), and the check that every criterion cites a provision that resolves before an Answer Key can be approved. |
question_slot_editing |
questions_workspace in the web app; over the API, only question_store_db (and qf_developer_api for a key) |
Editing a Question's slots and starting a new Question version, in the web app and over the API. |
quality_slot_facts |
question_slot_editing |
A Facts panel on a Question's Quality view in the web app. No API surface. |
advisor_question_routing |
The Advisor matches a live question to a published Question and asks for missing slot values before it answers. See Question routing. |
"Needs" means the feature does nothing useful, or refuses, unless that flag is on too. Turn the chain on together.
For a developer integration, the usual set is question_store_db, qf_developer_api and
question_catalog. Add questions_workspace for certification sign-off, and
question_slot_editing to edit slots or publish Question versions.
Turning a flag on¶
A platform admin uses the Feature flags panel in a tenant's settings, or the API:
curl -X PUT "$POLARIS/v1/brains/acme/flags/qf_developer_api" \
-H "Authorization: Bearer $PLATFORM_ADMIN_JWT" \
-H "Content-Type: application/json" \
-d '{"value": true}'
Overrides are kept per brain and per environment (local, dev, staging, prod). A change
takes effect on the next request; nothing restarts.
When a feature is off¶
A call that needs a flag that is off gets 403 with the code feature_disabled, whoever is
calling. The message names the flag:
{"error": {"code": "feature_disabled",
"message": "'qf_developer_api' (with 'question_store_db') is disabled for this brain"}}
It is a 403, not a 404, so a feature that is off can't be mistaken for a Question or run that doesn't exist. On the remote MCP endpoint a tool returns the same code in its result.
Reading which features are on¶
GET /v1/brains/{brain_id}/features returns every flag's effective value for the brain, but only
to a signed-in person. An API key can't call it (it gets 403 insufficient_scope). A key
finds out by calling what it needs: a feature that is off answers 403 feature_disabled and names
the flag. Ask the brain's platform admin which flags are on.
API keys¶
An API key is a long-lived bearer token, sk-polaris-…. Send it as
Authorization: Bearer sk-polaris-….
A key is bound to:
- one brain. It can only act on that brain. A key used on another brain's path gets
403 brain_forbidden. - one role:
Reader,CuratororAdmin. The role decides whether the key may hold the Curator scopes, and whether it sees rubrics. - an actor: the person it acts as. The audit trail records the actor and the key's id.
- its scopes: what it may do. A key without a scope a route needs gets
403 insufficient_scope.
A key doesn't expire. It works until it is revoked, and a revoked key stops at its next request.
Minting a key¶
A tenant Admin (for their own brain) or a platform admin mints a key, signed in. A key can't mint keys.
curl -X POST "$POLARIS/v1/brains/acme/api-keys" \
-H "Authorization: Bearer $ADMIN_JWT" \
-H "Content-Type: application/json" \
-d '{"label": "ci-evals", "role": "Reader",
"scopes": ["questions:read", "eval:run", "eval:submit"]}'
The response holds the raw key in key, once. Only its hash is stored. A key minted over REST
acts as the person who minted it (its actor). Without scopes a key gets advisor:read only; without role it is a
Reader.
Or at the CLI, on the server. A CLI key acts as its --actor; for Curator acts that must be the
login email of a real Curator or Admin of the brain (see The Curator-key rule):
bb apikey mint --brain-id acme --role Curator --actor dana@acme.example --label "dana-approvals" \
--scope questions:read --scope answer_key:approve --scope certification:sign_off
bb apikey list and bb apikey revoke <id> list and revoke keys. Over REST:
GET /v1/brains/{brain_id}/api-keys and DELETE /v1/brains/{brain_id}/api-keys/{key_id}.
Minting is refused (a 400, or a usage error at the CLI) for a scope that doesn't exist, such as
question:read, and for a Curator scope on a Reader key.
Scopes¶
Questions Framework scopes
| Scope | Allows |
|---|---|
questions:read |
List, read and match Questions; read a Question's slots, certified bindings and standing; the slot types; coverage; eval runs and their results; judge agreement; the eval budget. A Curator or Admin key also sees rubrics. |
questions:write |
Propose a Question; draft an Answer Key; propose a slot type; ask a named person to approve a draft; list the approval requests the key's actor made or is named on; withdraw the actor's own requests. On a Curator or Admin key, also save a whole rubric over a draft. |
eval:run |
Estimate a live run's cost, start a live run and read its progress. Also needed to have the judge grade answers you submit. Spends the eval budget. |
eval:submit |
Submit answers your own system gave, to be scored against an Answer Key. |
grades:submit |
Grade an eval result by hand, overriding the judge. The key must be a Curator or Admin key, and its actor must be an active Curator or Admin of the brain. It grades only as its actor. |
answer_key:approve |
Curator or Admin key. Approve a draft Answer Key. |
certification:sign_off |
Curator or Admin key. Sign off an eligible certification. Needs questions_workspace. |
questions:publish |
Curator or Admin key. Start a new version of a published Question. Needs question_slot_editing. |
slots:write |
Curator or Admin key. Edit a draft Question's slots, or a published Question's ask text (needs question_slot_editing). Approve a slot type someone else proposed. |
Other scopes
| Scope | Allows |
|---|---|
advisor:read |
The Advisor: the OpenAI-compatible /chat/completions API and the Advisor MCP endpoint /v1/mcp. The default for a new key. |
mcp:invoke |
The operator MCP server (stdio). Read tools only, unless the key also has mcp:write. |
mcp:write |
Operator MCP tools that change a corpus or the brain's store. |
mcp:any-brain |
Operator MCP tools on a brain other than the key's own. For platform operators. |
On the operator MCP server, answer_key:approve lets a key minted for a named person approve an
Answer Key, but only on a brain where question_store_db is off.
The Curator-key rule¶
Approving an Answer Key, signing off a certification, publishing a Question version and editing
slots are the acts the web app keeps for Curators and Admins. A key can do them only if it is a
Curator or Admin key and holds the act's scope. The role is checked when the key is minted and
again on every call. A Reader key that somehow holds one of these scopes gets
403 role_forbidden.
The key's actor must also be an active Curator or Admin account of this brain, checked on
every call (actor_not_a_curator otherwise; for an approval, approval_refused with that
detail.code). The audit records the key's id and its actor as the approver or signer. So:
- Agents never approve or sign off. A key whose actor is not a named person (an
agent:,agent/,bot:orsystem:name, a name ending(agent), or a placeholder such asadmin) is refused withnot_a_person. - A platform operator can't approve or sign off a tenant's work. A call signed in as a
platform admin is refused with
forbidden, even while acting as the tenant, and a key a platform operator minted acts as the operator, who has no Curator account in the brain. - A key follows its actor's account. Once the actor is deactivated or demoted to Reader, the key's Curator acts are refused, whatever role the key was minted with.
- A CLI key acts as its
--actor. A key minted withbb apikey mintwithout a real Curator's login as--actor(the default isapikey@polaris, which has no account) can't do Curator acts.
Approving your own draft is allowed: an Answer Key needs one approver, any Curator or Admin. Slot types are different: whoever proposed a slot type can't approve it.
Which flags a key needs¶
| A key calling… | Needs |
|---|---|
| Submit answers, grade, standing, the eval run list, judge agreement | question_store_db |
| List, read or match Questions | question_store_db, qf_developer_api, question_catalog |
| Everything else on the developer API, and the remote QF MCP endpoint | question_store_db, qf_developer_api |
| Sign-off and certification status | the above, and questions_workspace |
| Edit slots, publish a Question version | the above, and question_slot_editing |
Errors¶
Every developer API error uses one envelope:
{"error": {"code": "…", "message": "…", "detail": {…}}}.
| Status | Codes |
|---|---|
| 400 | invalid, bad_request, run_cap_exceeded |
| 401 | unauthorized, invalid_api_key, revoked_api_key |
| 402 | budget_exceeded, max_cost_exceeded |
| 403 | insufficient_scope, brain_forbidden, role_forbidden, feature_disabled, approval_refused, forbidden |
| 404 | not_found |
| 409 | conflict, version_conflict, citations_missing, idempotency_conflict, idempotency_in_progress |
| 422 | invalid_request (the body failed validation; detail.errors lists each problem) |
| 503 | judge_unavailable, idempotency_unavailable |
The API reference lists which errors each route returns.