Skip to content

Access: flags and keys

Two things decide whether a call to the Questions Framework works:

  1. Feature flags. Each QF feature is off for a brain until a platform admin turns it on.
  2. 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, Curator or Admin. 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: or system: name, a name ending (agent), or a placeholder such as admin) is refused with not_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 with bb apikey mint without a real Curator's login as --actor (the default is apikey@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.