Roles and permissions

Cusp ships four built-in roles. This page is the precise reference for what each can do; the users and roles guide covers signing in, sessions, and password handling. Roles are fixed in v1 — per-role configuration is a later addition — and a user can hold more than one.

What each role can do

Administrator

Full control of the deployment. Administrators reach every admin screen: content and media, content types and fields, users and roles, API tokens, themes, plugins, settings, the dashboard and health page, and backups and restore. Everything below is a subset of this.

Editor

Owns all content. An editor can create, edit, publish, schedule, and unpublish any document, browse the full version history, and manage the media library. Restoring a version — like all of site administration — is Administrator-only, and editors cannot reach users, roles, tokens, themes, plugins, settings, or backups.

Author

Creates and edits content but does not publish it. An author can create and edit documents, save drafts, upload media, and browse the version history of a document, but cannot publish, schedule, or unpublish — that is reserved for editors and administrators, so an author submits work for an editor to release. Restoring a version is Administrator-only. Authors have no access to site administration.

Subscriber

The lightest-weight authenticated account. Subscribers can sign in and read content but have no editing rights and no access to the admin's write surfaces. Cusp has no gated-content feature in v1, so a Subscriber account carries no special front-end privileges beyond being signed in.

How v1 enforces authorisation

Every admin route carries an explicit role check — there is no default-admin middleware that silently grants access, so a missing check is a bug rather than an inheritance. In v1 the check is by role: site-administration routes require Administrator; content and media routes admit Administrator, Editor, and Author; and publish, schedule, and unpublish narrow to Administrator and Editor. Authorisation does not vary by collection. It does turn on authorship for one case: an Author may edit only the documents they authored, while Editors and Administrators manage everyone's content. Authors cannot publish at all — their seeded permissions grant read and write on posts and media, with no publish action.

Each role is also seeded with a finer-grained set of (resource, action) permissions — the data the Users and roles screens display, with Administrator holding the wildcard *:* and the others holding explicit grants like posts:write and media:read. That permission set is the foundation for per-collection and per-document enforcement, which is a v1.x refinement; today the role itself is what each route checks.

Roles and API token scopes

The admin UI and the headless API share one authorisation path. An admin session is a token carrying the bare wildcard scope (*), so it satisfies every check. A minted API token usually carries narrower scopes — recipes:read, media:write, and so on — but an administrator can also mint the bare * scope onto a service token deliberately, granting it full access; there is no rule that withholds the wildcard from minted tokens. Roles govern people in the admin; scopes govern tokens on the API; both resolve through the same code. The headless API reference covers the scope grammar.