Permissions and roles

One global role per user, and a flat catalogue of resource:action keys. Workspace membership is a separate axis: which workspaces a user can reach.

The catalogue

37 keys. Admin holds all 37, contributor 18, viewer 7. schema:manage came with the schema builder.

• Source of truth: PERMISSIONS in packages/identity/server/src/lib/rbac/system-roles.ts.
• The seeder reconciles keys and grants on every boot, both directions — a new key reaches an existing install by deploying.
• Admin holds an enumerated list, not a wildcard: adding a key never widens anyone’s access by accident.

Checking what you hold

curl -b 'orthacms_session=…' https://cms.example.com/api/auth/me

{
    "id": "66666666-…",
    "email": "grace@example.com",
    "name": "Grace",
    "roleId": "55555555-…",
    "status": "active",
    "permissions": ["workspaces:read", "users:read", "content:read", "content:create", "…"]
}

A missing permission is a 403:

{ "statusCode": 403, "message": "Insufficient permissions", "error": "Forbidden" }

The roles

Grants worth knowing

API token scopes

A token’s scope becomes a permission set, evaluated by the same policy as a user’s role.

• Both read media: a content read hands back asset URLs.
• Only full uploads (a media field needs an asset id) and sets an entry’s audiences.
• No scope carries media:update, media:delete, content:export, content:import, content:approve, activity:manage or schema:manage.
• A read token can never ask for drafts.

Mint one (admin API, tokens:create):

curl -X POST https://cms.example.com/api/api-tokens \
  -b 'orthacms_session=…' -H 'Content-Type: application/json' \
  -d '{
    "name": "Marketing site build",
    "workspaceIds": ["7d0c…"],
    "scope": "read",
    "expiresAt": "2027-01-01T00:00:00.000Z"
  }'

{
    "id": "…",
    "name": "Marketing site build",
    "workspaceIds": ["7d0c…"],
    "scope": "read",
    "lookupPrefix": "…",
    "expiresAt": "2027-01-01T00:00:00.000Z",
    "lastUsedAt": null,
    "revokedAt": null,
    "createdAt": "…",
    "secret": "orthacms_…"
}

secret is returned once. workspaceIds takes 1–100 ids; omit expiresAt for a token that never expires (a past date is a 400).

Enforcing permissions in a plugin

Server — declare the key on the route; the guard evaluates it:

import { Controller, Get, UseGuards } from '@nestjs/common';
import { PERMISSIONS, PermissionsGuard, RequirePermissions } from '@orthacms/identity-server';
import { CurrentWorkspace, WorkspaceGuard } from '@orthacms/workspaces-server';

@UseGuards(PermissionsGuard, WorkspaceGuard)
@Controller('reports')
export class ReportsController {
    @RequirePermissions(PERMISSIONS.CONTENT_READ)
    @Get()
    list(@CurrentWorkspace() workspaceId: string) {
        return { workspaceId };
    }
}

• @RequirePermissions(a, b) needs all; @RequireAnyPermission(a, b) needs any.
• Keys come from the catalogue; a plugin does not add its own.

Admin — gate the UI with the same key:

import { useHasPermission } from '@orthacms/identity-admin';

const canPublish = useHasPermission('content:publish');

Hiding a control is a courtesy; the server decides. Do both. See server plugins.

What the model cannot express

To narrow what someone reaches, use workspace membership: put the content in a workspace they are not a member of.