Security

CM Box controls who can do what through a granular permission model administered from the Security section of the admin area. This page explains the model from the administrator’s seat and walks through the day-to-day tasks: syncing users, assigning roles, editing a role’s permissions, and creating service accounts. For the full catalog of permission keys, scopes, and bundle contents, see the permissions reference.

How the model fits together

• Users are people. They arrive by directory sync from WorkOS or are created directly in the admin UI, and they sign in with their email address.
• Groups collect users. Directory sync creates groups automatically from your identity provider’s groups.
• Roles are the unit you grant permissions to. A user’s effective permissions are the union of the roles assigned to them directly and the roles assigned to every group they belong to. Permissions never attach to a user or group directly — always through a role.
• Service accounts are non-human identities for API callers and integrations. They hold roles exactly like users and authenticate with client credentials — see Authentication.

The built-in admin role bypasses every permission check and cannot be deleted, so you can never lock yourself out.

What a role grants

A role composes its permissions from three layers:

Layer	What it does	Scope
Bundles	Named permission sets the role inherits	Always global — a bundle’s permissions apply to all repositories and sites
Scoped permissions	Individual permission keys granted globally, per repository, or per site	As granted; content keys can also be limited to one content type
Overrides	Extra single-key grants and revokes applied last	Global; a revoke always wins

The practical rule: use bundles for the broad shape of a role, scoped permissions when a role should act in only some repositories or sites, and revoke overrides to carve a single capability out of an otherwise suitable bundle.

The built-in bundles

CM Box seeds eleven bundles. You can also define your own on the Permission Bundles tab.

Bundle	Grants
Viewer	Read-only access
Content Contributor	Create and edit content and folders; no publish, no delete
Content Editor	Contributor plus delete, publish, and version restore
Site Builder	Build and edit sites — pages, navigation, settings, preview; no publish
Site Publisher	Site Builder plus publish and scheduled publish
Package Author	Create, edit, and stage update packages
Package Publisher	Merge and publish packages
Content Architect	Manage taxonomies, categories, and content types
Repository Admin	Configure repositories — settings, security config, features, crawls
Security Admin	Manage users, groups, roles, and service accounts
System Admin	System-level settings, storage, webhooks, indexes, workflows, queue, and instance setup

Security administration itself is guarded by the admin.security.* permission keys; the Security Admin bundle carries them all.

The Security admin area

In the admin area, open Security. The page is organized into five tabs: Users, Groups, Roles, Service Accounts, and Permission Bundles. Each lists its objects with edit and delete actions, and each object type has a create button (Create User, Create Group, Create Role, Create Service Account, Create Bundle). Clicking a user, role, or service account opens its detail page for membership and permission editing.

Sync users from your WorkOS directory

CM Box provisions users and groups from the WorkOS directory configured for your instance (see Instance setup and licensing). The sync matches users by email address, creates any directory groups it finds, and updates each user’s group membership. Roles you assigned locally are kept across syncs — only group membership is overwritten from the directory.

1. On the Users tab, click Sync Users (requires the admin.security.sync permission).
2. The message “User synchronization from directory started.” confirms the sync is running; refresh the list to see new users and groups.

Run a sync whenever people join or change groups in your identity provider. You can also create users and groups directly in CM Box with Create User and Create Group — local and synced identities coexist.

Assign roles

Roles reach people two ways:

• Per user — open the user from the Users tab. The User Profile page has a Roles panel (Add Role) and a Groups panel (Add Group).
• Per group (recommended for teams) — open a group’s edit page and use its Roles tab to attach roles. Everyone in the group inherits them, including users added by future directory syncs.

You can also assign from the other direction: a role’s edit page has an Assign Members panel that searches users, service accounts, and groups.

Edit a role’s permissions

1. On the Roles tab, open the role and go to its Permissions tab.
2. In Permission Bundles, check the bundles the role should inherit. Remember bundles grant across all repositories and sites.
3. In Global Permissions, grant individual keys that should apply everywhere — use sparingly.
4. In Per-Repository Permissions, pick a repository and check the keys the role holds there. Type-aware keys (marked with a type-aware badge) can be limited to specific content types.
5. In Per-Site Permissions, do the same per site.
6. In Bundle Overrides, add single-key grants or revokes. A revoke removes the key even if a bundle grants it.
7. Click Save Permissions.

Test the result by signing in with a real account that holds only this role before relying on it — permission checks fail closed, so a missing grant means denied access.

Create a service account

1. On the Service Accounts tab, click Create Service Account and enter a Name and Description.
2. A Save Service Account Info dialog shows the account’s Client ID and Client Secret with the warning: “Save the following Client ID and Client Secret now. You won’t be able to see the Client Secret again!” Store both in your secret manager now — the secret is stored hashed and cannot be displayed again. To replace a lost secret, delete the account and create a new one.
3. Open the new account’s profile page and assign it the roles (or groups) that carry the permissions its API calls need. Prefer the narrowest bundle that covers the job — for example Viewer for a read-only sync.

The account authenticates with the OAuth 2.0 client-credentials flow — see Authentication for the token exchange.

Related

• Permissions reference — every permission key, scope, and bundle definition
• Authentication — the service-account token flow
• Upgrade CM Box — the 2.0 security migration
• Repositories — repository-level configuration