Access Groups
Access groups provide fine-grained permission control for Total CMS, allowing you to restrict what users can access and modify in both the admin dashboard and via the REST API.
Overview
Section titled “Overview”Access groups work at two levels:
- Middleware Enforcement: Routes are protected by middleware that checks permissions before allowing access
- UI Controls: Template helper functions hide/show UI elements based on permissions
Super admin users (members of the admin group in the default auth collection) bypass all access checks automatically.
Users without a group
Section titled “Users without a group”A user of the default auth collection who belongs to no group gets the built-in default group, which reads every collection and schema and changes nothing.
A member of any other auth collection, such as one that takes public registrations, gets no permissions without a group. They can sign in, open pages gated to signed-in users, download files whose File Access Groups include default, and edit their own profile. They can’t read or change collections through the admin, the REST API or MCP. To give members that, add a group to the collection’s Registration Groups or assign one yourself.
Before 3.6.5, these members also got the default group, so anyone who signed up could read every collection through the REST API, including drafts and the admin users’ names and email addresses.
Access Group Structure
Section titled “Access Group Structure”Access groups are defined in tcms-data/.system/access-groups.json:
{ "groups": [ { "id": "editor", "description": "Blog and news editor", "permissions": { "collectionsMeta": { "operations": ["read"], "all": false, "allowed": ["blog", "news"] }, "collections": { "operations": ["create", "read", "update", "delete"], "all": false, "allowed": ["blog", "news"] }, "schemas": { "operations": ["read"], "all": false, "allowed": ["blog", "news"] }, "builder": true, "mailer": false, "playground": true, "docs": true, "utils": { "all": false, "allowed": ["cache-manager"] }, "settings": { "all": false, "allowed": [] } } } ]}Manage groups in Utilities → Access Groups, or from the command line with tcms access-group:list, access-group:get, access-group:set and access-group:patch — see CLI. Don’t edit the file by hand: a misspelled section or operation saves a group that quietly grants nothing, which the CLI refuses.
CRUD Operations
Section titled “CRUD Operations”Total CMS uses CRUD (Create, Read, Update, Delete) operations for fine-grained permission control:
create- Create new resources/objectsread- View/list/fetch resourcesupdate- Modify existing resourcesdelete- Delete/remove resources
These operations replace the older HTTP method approach and provide clearer, more intuitive permission control.
Permission Types
Section titled “Permission Types”Collections
Section titled “Collections”Collections have two separate permission levels:
Collection Settings (collectionsMeta)
Section titled “Collection Settings (collectionsMeta)”Controls access to managing collection definitions (creating/editing/deleting collections themselves):
"collectionsMeta": { "operations": ["read", "update"], "all": false, "allowed": ["blog", "news"]}create- Create new collectionsread- View collection definitionsupdate- Edit collection settingsdelete- Delete collections
Collection Objects (collections)
Section titled “Collection Objects (collections)”Controls access to objects within collections:
"collections": { "operations": ["create", "read", "update", "delete"], "all": true, "allowed": []}create- Create new objectsread- View/list objectsupdate- Edit objectsdelete- Delete objectsall- Iftrue, access all collections; iffalse, only those inallowedallowed- Array of specific collection IDs
Owned collections. A grant on a collection covers every object in it — unless the collection names an ownerProperty. Then anyone who is not a super admin is limited to the objects they created: the same read/update/delete grant, applied to their own objects only, with the owner stamped on create. Access groups decide which collections; the owner property decides which objects. Use it for member-submitted content, guest authors, and anything where “yours” matters. The owner property can be a list of user ids for shared ownership, and ownerCollection limits owners to one auth collection.
A refusal is the same 403 “Access denied” whichever check made it; the access log records which, as reason: group (the group did not grant the operation), reason: owner (the object belongs to someone else) or reason: protected (a non-admin write to a protected property through a property route, or a clone or collection import refused on a collection with protected properties, or a clone whose body names another target collection).
Schemas
Section titled “Schemas”"schemas": { "operations": ["create", "read", "update", "delete"], "all": false, "allowed": ["blog", "product"]}create- Create new schemasread- View schemasupdate- Edit schemasdelete- Delete schemasall- Iftrue, access all schemas; iffalse, only those inallowedallowed- Array of specific schema names
Site Builder
Section titled “Site Builder”"builder": true // or falseSimple boolean for full access or no access to the Site Builder (pages and templates). Groups saved before this permission existed fall back to their legacy templates value.
Settings
Section titled “Settings”"settings": { "all": false, "allowed": ["general", "cache"]}all- Iftrue, access all settings sectionsallowed- Array of specific setting section names (e.g., “general”, “cache”, “auth”, “mailer”)
Extensions
Section titled “Extensions”"extensions": { "all": true, "allowed": []}all- Iftrue, the group can see and use every extension’s admin surfaceallowed- Array of extension IDs (e.g.,"acme/seo-pro") whenallisfalse
Controls which extensions’ nav items, dashboard widgets, and admin pages this group can see and open. It only applies to extension pages registered with permission: 'any' — pages an extension marks admin always require a super admin, and groups cannot widen that. Groups saved before this block existed behave as all: true, so restricting is always an explicit operator choice. The form only lists extensions that actually register admin surface.
"utils": { "all": false, "allowed": ["cache-manager", "jumpstart"]}all- Iftrue, access all utility pagesallowed- Array of specific utility page names
Some utilities also gate the API routes behind their page: cache for clearing caches and dev mode, import for the site importers, and jobqueue or import for clearing the job queue.
Boolean Permissions
Section titled “Boolean Permissions”Simple true/false for features without granular control:
builder- Access to the Site Builder, including template editing (groups saved before this permission existed fall back to their legacytemplatesvalue)mailer- Access to mailer/email functionalityplayground- Access to Twig playgrounddataviews- Access to Data Viewsdocs- Access to documentationinlineEdit- May edit values in place (the pencil in collection tables). Also requiresupdateon the collection, and the site-wide Settings → Dashboard → Inline Editing switch. Groups saved before this permission existed read astrue, so nothing changes on upgrade
Twig Helper Functions
Section titled “Twig Helper Functions”Total CMS provides helper functions to check permissions in your templates, allowing you to hide/show UI elements based on the current user’s access groups.
Collections
Section titled “Collections”Check specific collection object access:
{% if cms.auth.canAccessCollection('blog', 'read') %} <a href="/admin/collections/blog">View Blog Posts</a>{% endif %}
{% if cms.auth.canAccessCollection('blog', 'create') %} <a href="/admin/collections/blog/new">New Post</a>{% endif %}
{% if cms.auth.canAccessCollection('blog', 'update') %} <button>Edit Post</button>{% endif %}
{% if cms.auth.canAccessCollection('blog', 'delete') %} <button class="delete">Delete Post</button>{% endif %}Check general collection object access:
{% if cms.auth.canAccessCollectionsOperation('read') %} <p>You can view collections</p>{% endif %}Check collection metadata access:
{% if cms.auth.canAccessCollectionMeta('blog', 'read') %} <a href="/admin/collections/blog/settings">View Collection Settings</a>{% endif %}
{% if cms.auth.canAccessCollectionMeta('blog', 'update') %} <button>Edit Collection Settings</button>{% endif %}
{% if cms.auth.canAccessCollectionMeta('blog', 'delete') %} <button class="delete">Delete Collection</button>{% endif %}Check general collection metadata access:
{% if cms.auth.canAccessCollectionsMetaOperation('read') %} <a href="/admin/collections">View Collections List</a>{% endif %}
{% if cms.auth.canAccessCollectionsMetaOperation('create') %} <a href="/admin/collections/new">New Collection</a>{% endif %}Get list of accessible collections:
{% for collection in cms.getAccessibleCollections('read') %} <li>{{ collection }}</li>{% endfor %}Schemas
Section titled “Schemas”Check specific schema access:
{% if cms.auth.canAccessSchema('blog', 'read') %} <a href="/admin/schemas/blog">View Blog Schema</a>{% endif %}
{% if cms.auth.canAccessSchema('blog', 'update') %} <a href="/admin/schemas/blog/edit">Edit Schema</a>{% endif %}
{% if cms.auth.canAccessSchema('blog', 'delete') %} <button class="delete">Delete Schema</button>{% endif %}Check general schemas access:
{% if cms.auth.canAccessSchemasOperation('read') %} <a href="/admin/schemas">View Schemas</a>{% endif %}
{% if cms.auth.canAccessSchemasOperation('create') %} <a href="/admin/schemas/new">New Schema</a>{% endif %}Site Builder
Section titled “Site Builder”Check Site Builder access (boolean):
{% if cms.auth.canAccessBuilder() %} <a href="/admin/builder">Builder</a>{% endif %}Extensions
Section titled “Extensions”Check extension access (boolean):
{% if cms.auth.canAccessExtension('acme/seo-pro') %} <a href="/admin/ext/acme/seo-pro/reports">SEO Reports</a>{% endif %}Check specific utils page:
{% if cms.auth.canAccessUtil('cache-manager') %} <a href="/admin/utils/cache-manager">Cache Manager</a>{% endif %}
{% if cms.auth.canAccessUtil('jumpstart') %} <a href="/admin/utils/jumpstart">JumpStart</a>{% endif %}Check general utils access:
{% if cms.auth.canAccessUtils() %} <a href="/admin/utils">Utils</a>{% endif %}Boolean Permissions
Section titled “Boolean Permissions”Check mailer access:
{% if cms.auth.canAccessMailer() %} <a href="/admin/mailer">Mailer</a>{% endif %}Check playground access:
{% if cms.auth.canAccessPlayground() %} <a href="/admin/playground">Twig Playground</a>{% endif %}Check docs access:
{% if cms.auth.canAccessDocs() %} <a href="/admin/docs">Documentation</a>{% endif %}Admin Check
Section titled “Admin Check”Check if user is super admin:
{% if cms.auth.isAdmin() %} <div class="admin-only-feature"> <a href="/admin/utils/access-groups">Manage Access Groups</a> </div>{% endif %}Super admins bypass all access checks and have full access to everything.
Practical Examples
Section titled “Practical Examples”Conditional Navigation Menu
Section titled “Conditional Navigation Menu”<nav> {% if cms.auth.canAccessCollectionsMetaOperation('read') %} <a href="/admin/collections">Collections</a> {% endif %}
{% if cms.auth.canAccessSchemasOperation('read') %} <a href="/admin/schemas">Schemas</a> {% endif %}
{% if cms.auth.canAccessBuilder() %} <a href="/admin/builder">Builder</a> {% endif %}
{% if cms.auth.canAccessUtils() %} <a href="/admin/utils">Utils</a> {% endif %}
{% if cms.auth.isAdmin() %} <a href="/admin/utils/access-groups">Access Groups</a> {% endif %}</nav>Filtered Collection List
Section titled “Filtered Collection List”<ul>{% for collection in collections %} {% if cms.auth.canAccessCollection(collection.id, 'read') %} <li> <a href="/admin/collections/{{ collection.id }}">{{ collection.name }}</a>
{% if cms.auth.canAccessCollection(collection.id, 'create') %} <a href="/admin/collections/{{ collection.id }}/new">New Item</a> {% endif %}
{% if cms.auth.canAccessCollectionMeta(collection.id, 'update') %} <a href="/admin/collections/{{ collection.id }}/settings">Settings</a> {% endif %} </li> {% endif %}{% endfor %}</ul>Collection Object Actions
Section titled “Collection Object Actions”<div class="object-actions"> {% if cms.auth.canAccessCollection(collection, 'create') %} <a href="/admin/collections/{{ collection }}/new" class="btn">New Object</a> {% endif %}
{% if cms.auth.canAccessCollection(collection, 'update') %} <button class="btn" data-action="edit">Edit</button> {% endif %}
{% if cms.auth.canAccessCollection(collection, 'delete') %} <button class="btn btn-danger" data-action="delete">Delete</button> {% endif %}</div>Schema Management Buttons
Section titled “Schema Management Buttons”<div class="schema-actions"> {% if cms.auth.canAccessSchemasOperation('create') %} <a href="/admin/schemas/new" class="btn">New Schema</a> {% endif %}
{% if cms.auth.canAccessSchema(schema.id, 'update') %} <a href="/admin/schemas/{{ schema.id }}/edit" class="btn">Edit</a> {% endif %}
{% if cms.auth.canAccessSchema(schema.id, 'delete') %} <button class="btn btn-danger" data-schema="{{ schema.id }}">Delete</button> {% endif %}</div>Common Access Group Configurations
Section titled “Common Access Group Configurations”Full Admin
Section titled “Full Admin”{ "id": "admin", "description": "Full administrative access", "permissions": { "collectionsMeta": { "operations": ["create", "read", "update", "delete"], "all": true, "allowed": [] }, "collections": { "operations": ["create", "read", "update", "delete"], "all": true, "allowed": [] }, "schemas": { "operations": ["create", "read", "update", "delete"], "all": true, "allowed": [] }, "builder": true, "mailer": true, "playground": true, "docs": true, "utils": { "all": true, "allowed": [] }, "settings": { "all": true, "allowed": [] } }}Content Editor
Section titled “Content Editor”{ "id": "editor", "description": "Full CRUD access to specific collections", "permissions": { "collectionsMeta": { "operations": ["read"], "all": false, "allowed": ["blog", "news"] }, "collections": { "operations": ["create", "read", "update", "delete"], "all": false, "allowed": ["blog", "news"] }, "schemas": { "operations": ["read"], "all": false, "allowed": ["blog", "news"] }, "mailer": false, "playground": true, "docs": true, "utils": { "all": false, "allowed": [] }, "settings": { "all": false, "allowed": [] } }}Read-Only Viewer
Section titled “Read-Only Viewer”{ "id": "viewer", "description": "Read-only access to all collections", "permissions": { "collectionsMeta": { "operations": ["read"], "all": true, "allowed": [] }, "collections": { "operations": ["read"], "all": true, "allowed": [] }, "schemas": { "operations": ["read"], "all": true, "allowed": [] }, "builder": true, "mailer": false, "playground": true, "docs": true, "utils": { "all": false, "allowed": [] }, "settings": { "all": false, "allowed": [] } }}Single Collection Specialist
Section titled “Single Collection Specialist”{ "id": "blogger", "description": "Full CRUD access to blog collection only", "permissions": { "collectionsMeta": { "operations": ["read"], "all": false, "allowed": ["blog"] }, "collections": { "operations": ["create", "read", "update", "delete"], "all": false, "allowed": ["blog"] }, "schemas": { "operations": ["read"], "all": false, "allowed": ["blog"] }, "mailer": false, "playground": true, "docs": true, "utils": { "all": false, "allowed": [] }, "settings": { "all": false, "allowed": [] } }}Best Practices
Section titled “Best Practices”-
Use UI Controls Everywhere: Always check permissions before showing links, buttons, or forms. Don’t rely on middleware alone - good UX means hiding what users can’t access.
-
Check Appropriate Operations: Use the appropriate CRUD operation for the action:
readfor viewing/listingcreatefor creating new resourcesupdatefor modifying existing resourcesdeletefor deleting resources
-
Distinguish Collections from Collection Settings:
- Use
canAccessCollection()for working with objects within a collection - Use
canAccessCollectionMeta()for managing collection definitions
- Use
-
Graceful Degradation: Hide buttons/actions users can’t perform rather than showing disabled buttons.
-
Admin-Only Features: Use
cms.auth.isAdmin()for features that should never be delegated (like managing access groups, API keys, or user accounts). -
Operation-Level Checks: Use general operation checks (e.g.,
canAccessCollectionsOperation()) for listing pages where no specific resource is selected yet. -
Principle of Least Privilege: Grant users only the minimum permissions they need to accomplish their tasks.
Admin-Only Routes
Section titled “Admin-Only Routes”Some routes require super admin access and cannot be delegated via access groups:
- Access Groups Management:
/admin/utils/access-groups - API Key Management:
/admin/apikeys/* - User Management:
/admin/users/*
These routes use AdminOnlyMiddleware which only allows super admin users.
CRUD Operations Reference
Section titled “CRUD Operations Reference”| Operation | Purpose | Example Use Case |
|---|---|---|
create | Create new resources | Add new blog post, create collection |
read | View/list resources | View blog posts, list schemas |
update | Modify existing resources | Edit blog post, update collection settings |
delete | Remove resources | Delete blog post, remove collection |