Skip to content

Keys, capabilities and policy

Three things decide what an application may do in Core. A key is how the application identifies itself. Capabilities decide which features exist for that key. The policy decides what the key reaches within those features: which models, which tools, which knowledge and which data.

Keys

An API key belongs to one organisation and stands for one application. The application sends the key's secret as a bearer token on every request; there is no sign-in and no token exchange.

  • Create one key per application. Usage, caps and the audit trail are kept per key, so that is how you see who did what.
  • The secret appears once, when the key is created. If you lose it or it leaks, you rotate the key: the old secret stops working at once, the id and the history stay.
  • A key can have a monthly cost cap and an expiry date.
  • GET /key returns what a key is and may do: its organisation, capabilities and policy.

People who sign in to the console are not keys but administrators. They administer the organisation; a key calls it.

Capabilities

A capability is a switch for a feature: threads for conversations, tooling for tools, knowledge for knowledge, agents for agents. The full list is in Capabilities.

A capability only works when it is on in two places:

  1. in the organisation's ceiling (Permitted capabilities), and
  2. on the key itself.

The ceiling is set by the administrator of the organisation above. On the key, the organisation's own administrator chooses, within that ceiling. When a capability is off, the routes behind it answer 404, the same answer as a path that does not exist.

Some capabilities need another: memory requires knowledge, background runs require conversations, artifacts require files. The management capability is unlike the rest: a key with management administers the organisation and the organisations beneath it through the API. Give it to few keys.

Policy

A capability says a key may use tools. The policy says which. A policy is a list of rules, and each rule permits or forbids one kind of thing:

Kind A rule decides
Models, Routers which models and routers a turn may use
Tools which tools the model may call
Agents, Prompts, Skills, Schedules, Workflows, Files by name, Datastores which of them the key reaches, by name
Knowledge collections, Knowledge indexes, Knowledge graphs, Knowledge sources which knowledge the key reaches
Conversations, Memory records, Stored files, Datastore rows which rows a request reaches

A rule selects by name (with a pattern such as support-*) or by labels you attach to resources yourself (such as department: support). Three facts decide the outcome:

  • Forbid always wins.
  • Nothing is allowed without a rule that permits it.
  • The organisation's policy and the key's policy must both allow it. A key can narrow what the organisation allows, never widen it.

When the organisation sits under another, the policies of the organisations above narrow this further: for models, routers, tools, destinations, artifact downloads and memory writes, and for the allowed regions (Policy).

What no rule permits does not exist for the key: it is missing from lists and a request with its id answers 404.

A rule can also name the actions it is about: see (list and read), use (in a turn, a run or a call), change (write in the API: create, edit, relabel) and delete. A rule that names none covers all of them. With actions, everybody can use an agent while only administrators change it. A thing the key sees but may not use, change or delete answers 403, and so does creating something, renaming it or giving it labels no rule permits: there is nothing yet to hide. The tools a key reaches also decide which connectors, MCP servers, scripts and toolsets it lists when a request names a person (Separate seeing, using and changing).

A new key starts with default rules that permit all models, tools and library items. Two things are closed by default until you add a rule for them: a turn writes no memory, and nothing is shared with a link. Which hosts a tool may contact is decided by the organisation with its Allowed hosts list; a key with no rule of its own about hosts reaches exactly those (Allowed destinations).

Besides rules, a policy has settings. The main ones:

  • Require an agent: every turn must name an agent and runs it as it is defined. For a key you hand to strangers, such as visitors of a chat on a website.
  • A subject is compulsory: every request must name the person it is for.
  • Allowed regions: models, tools and other destinations outside these regions are refused (Keep calls in your regions).

Per person: the subject

When several people use your application through the same key, each request names the person it is for: the subject, in the X-Core-Subject header. It holds an id your application chooses and optional attributes, such as a department. Rules in the policy can depend on it: a person reaches her own conversations and the shared ones, or only the knowledge sources that carry her department's label. Core manages no accounts for these people; your application supplies the identity. See Build for people.

When to use which

You want to Use
switch a whole feature off for a customer the organisation's capability ceiling
switch a feature off for one application the key's capabilities
limit one application to certain models, tools or knowledge rules in the key's policy
a limit that holds for every key of a customer the organisation's policy
tell people behind the same key apart a subject, labels and rules with When

How it fits together

  • A key belongs to one organisation; that organisation's ceiling and policy apply to all of its keys.
  • What an agent brings is checked against the policy of the key that calls it. An agent never gives a key more reach.
  • Tools, knowledge and models are each reached through a rule in the policy.
  • Every policy decision is written to the audit trail (Insight).

Read on

Tutorial: Set up a new customer organisation.