# API keys: scopes are a role ceiling

URL: https://kywi-docs-production.up.railway.app/agent/api-keys-scopes-are-a-role-ceiling
Type: docPage

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 offers

## Key management is an api-mode-only tool set

`create_api_key`, `list_api_keys` and `revoke_api_key` register only when the developer server resolves to api mode — see [The developer server's mode decides your tool list](/agent/the-developer-servers-mode-decides-your-tool-list/). In filesystem mode, none of the three exist to call.

## These three tools call the wrong path, and say nothing about it

As shipped, every call to `create_api_key`, `list_api_keys` or `revoke_api_key` hits `/api-keys`, and the route Kywi actually registers is `/auth/api-keys`. What you will see is not an error: the HTTP client treats a 404 as a result rather than a failure and hands the body straight back, so the tool answers, looking successful, with `{"error":{"code":"NOT_FOUND","message":"Route not found"}}`. An agent that doesn't read that payload will tell you the key was created. Nothing was created.

## 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](/governing/roles-and-the-capability-matrix/) for what each level can do outside of API keys.
