Skip to content

API keys: scopes are a role ceiling

A key’s scopes cap the role its requests run as; read, write and publish together still ceiling below the role that content deletion requires.

An API key's scopes don't grant a role directly — each scope maps to the highest role it allows, and every request the key makes runs as whichever is lower: that ceiling, or the role of the person who created the key.

The ceiling each scope buys

read ceilings at reader; write at author; publish at editor; admin and developer both ceiling at siteAdmin. No scope reaches superAdmin — the most destructive operations stay session-only regardless of what a key is scoped to. Combining scopes takes the highest ceiling among them, not the sum: read plus write plus publish still ceilings at editor, one level below what deleting content requires.

Why read + write + publish still can’t delete

Content actions carry their own minimum role — reading needs reader, writing needs author, publishing needs editor, deleting needs siteAdmin. A key scoped read, write, publish ceilings at editor, so it 403s the moment it tries delete_content, no matter how permissive the key's owner is. Reaching siteAdmin from a key means adding admin or developer to its scopes specifically — there's no path to it through the content-action scopes alone.

the scopes a key carries — the same list the admin’s key form offersjson
{
  "name": "content-agent",
  "scopes": ["read", "write", "publish"]
}

A person creates the key, not an agent

Correcting that path would not make create_api_key work. The create route refuses any request that authenticated with an API key at all — an API key cannot create API keys — and the developer server has no other way to authenticate: it sends KYWI_MCP_DEV_KEY on every request. A read-scoped key that could mint an admin-scoped one would walk straight past the ceiling this page is about, so key creation is session-only on purpose: a signed-in person, in the admin, under Web Services → API Keys (reachable by any editor, not just a siteAdmin). Listing and revoking carry no such rule — those two would work from the developer server once the path is fixed.

The ladder these ceilings sit on

The five roles a ceiling or a content action can name are the same ladder used everywhere else in Kywi, from session logins to content permissions. See Roles and the capability matrix for what each level can do outside of API keys.