Skip to main content

​
Authentication

Every request carries a bearer credential:
Three credentials are accepted, and Briefed ID resolves them by different routes:
  • an API key (brf_live_…), for programmatic and agent use
  • a session JWT, issued to the signed-in browser app
  • an OAuth access token, issued when you approve a client such as the MCP server. It resolves to you rather than to a key, so it carries no scopes and is bounded by your entitlement
Create keys at id.briefedmedia.com/api-keys. A key is shown once at creation and stored only as a hash, so it cannot be recovered later.

​
Which plans have API access

The Workflows API is available on Max and Team seats. Pro includes Workflows in the browser but not programmatic access, and cannot create API keys. These scopes cover the Workflows surface only. Terminal is reachable as a step inside a workflow graph (terminal.*) and has no API of its own. Anya does: her own surface under /anya, gated by the anya entitlement rather than by these scopes, and a key granted Workflows scopes is not thereby granted Anya. A caller on a plan without it receives 402:

​
Product scoping

A key carries a set of products. To reach this API the key must include briefed_research in its products. A key scoped only to Consumer Intelligence resolves as a valid key but is refused here.

​
Scopes

Running a workflow draws on your research usage allowance. Reading one does not. They are therefore separate grants, so a key handed to an automation, a script, or an MCP server can be made incapable of incurring cost. write:workflows implies read:workflows; a key that can publish can obviously list. A request needing a scope the key lacks returns 403:

​
Which routes need which

Classification is explicit, not inferred from the HTTP method. Two POSTs are reads because they change nothing and cost nothing. An agent must be able to check its own work without also being able to spend:
  • POST /api/v1/workflows/catalogue/validate-definition
  • POST /api/v1/workflows/catalogue/resolve-subjects
Every other mutating route requires write:workflows, including any added in future.
A session JWT is not scope-limited. A signed-in user is bounded by their plan entitlement rather than by a key, so scopes apply to API keys only.
Issue two keys rather than one:
  • a read-only key (read:workflows) for dashboards, monitoring, CI checks, and any agent that inspects but must not act
  • a write key (write:workflows) held by the small number of callers that publish or run, with an expiry set
Keys support expiry, revocation, and an IP allowlist. Revoking takes effect within the credential cache TTL of 60 seconds.

​
Failure modes