Permissions

An identity adapter verifies who is signed in. Its optional authorize method decides what writes that editor may perform. Without that method, authenticated editors have full write access subject to collection capabilities. Roles on an identity do not restrict access by themselves.

Add a write policy

First configure an authoritative identity provider. Add the policy to the adapter it returns. This example lets an editor save changes to pages and a publisher edit and publish pages; only admin can perform the other actions. Role names are project-defined.

import type { IdentityAdapter } from '@caretcms/core';
import { verifyEditorSession } from './auth/verify-editor-session';

export function identityProvider(): IdentityAdapter {
  return {
    async authenticate(request) {
      // Project-owned function: verify the existing sign-in session server-side.
      const user = await verifyEditorSession(request);
      if (!user) return null;
      return { id: user.id, name: user.name, roles: user.roles };
    },
    loginUrl: ({ redirectTo }) => `/login?returnTo=${encodeURIComponent(redirectTo)}`,
    authorize({ identity, action, collection }) {
      const roles = identity.roles ?? [];
      if (roles.includes('admin')) return true;
      if (collection !== 'pages') return false;
      if (action === 'edit') {
        return roles.includes('editor') || roles.includes('publisher');
      }
      if (action === 'publish') return roles.includes('publisher');
      return false;
    },
  };
}

verifyEditorSession is an application function you must implement using your authentication service. Do not return a constant identity or trust roles supplied by the browser. IDs must match /^[A-Za-z0-9_-]{1,64}$/.

The policy receives identity, request, action, and the available collection and id. Only literal true grants access. Exceptions and other return values deny access. Decisions are reused within a request, then reevaluated on later requests.

Actions

Action	Controls
edit	Field and body saves, entry creation, reordering, layout changes
publish	Publishing drafts, retrying deployment, restoring history
delete	Drafting deletion and publishing a deletion
manageCollections	Creating/deleting collection definitions
upload	Uploading files

Deletion needs both edit and delete. Restore needs edit and publish. Bulk reorder checks every entry. Bulk publication checks permissions for all targeted drafts before the first write, including deletion permission where needed.

A policy makes content saves private

With authorize configured, content saves use the editor’s private draft even in server delivery. An editor without publish permission cannot save directly to shared content. Storage must support makeEditorOverlay; otherwise writes fail with 503 and public content remains unchanged.

Studio hides actions when it can evaluate the relevant scope. The server checks every request, including uploads and requests made outside the UI.

What a policy does not provide

• It does not hide entries, schemas or history from authenticated Studio users. This is a write policy, not read-level confidentiality.
• Editors cannot open or publish another identity’s drafts through this API. Giving someone a publisher or reviewer role does not create a review queue.
• Submission, approvals, comments and shared draft workflows need a separate application model. No user/role management screen ships in Studio.
• Collection settings such as deletable: false still apply.

See Saving and publishing for draft ownership and what happens when the editor signs out.