dotCMS

dotCMS Roles API

User role and permission management

GitHub OpenAPI
Business capability
Identity & Access Management BC-620.20

Operations 19

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /api/role/loadbyid/{params} Load full role details (legacy endpoint) · Load role by ID (deprecated) #
Ask an LLM
“How did the old admin UI load a role's full properties by id?”
“Is there a deprecated endpoint that returns every property of a role?”
Tell an agent
Load role details with the deprecated loadbyid endpoint using {params}.
Fetch the role via the legacy loadbyid call for {params}.
GET /api/role/loadbyname/{params} Filter the role tree by name (legacy endpoint) · Load roles by name filter (deprecated) #
Ask an LLM
“Can I get a role tree trimmed to leaves whose name contains some text on the old API?”
“Which deprecated call filters the role tree by name?”
Tell an agent
Filter the role tree by name using the legacy loadbyname call with {params}.
Get the deprecated name-filtered role tree for {params}.
GET /api/role/loadchildren/{params} Lazy-load a role's children (legacy endpoint) · Load role children (deprecated) #
Ask an LLM
“How does the deprecated API return the first-level children of a role?”
“What does the legacy loadchildren call return when no role id is given?”
Tell an agent
Load first-level child roles with the legacy loadchildren call for {params}.
Expand the old role tree node {params} one level down.
GET /api/v1/roles List the top-level roles · Load root roles #
Ask an LLM
“What are the root roles in my dotCMS role hierarchy?”
“Can I get the root roles with their children included?”
Tell an agent
List the root roles.
Show root roles with children loaded set to {loadChildrenRoles}.
POST /api/v1/roles Create a new role · Create new role #
Ask an LLM
“How do I create a new role under an existing parent role?”
“Can I let a new role edit users or permissions when I create it?”
Tell an agent
Create a role named {roleName}.
Create role {roleName} under parent {parentRoleId} with key {roleKey}.
POST /api/v1/roles/{roleid}/users/{userId} Grant a role to a user · Grant a role to a user #
Ask an LLM
“How do I give a user a role directly?”
“What happens if I grant a role the user already has?”
Tell an agent
Grant role {roleid} to user {userId}.
Add user {userId} as a direct member of role {roleid}.
GET /api/v1/roles/checkuserroles/userid/{userId}/roleids/{roleIds} Check if a user holds any of given roles · Check user roles #
Ask an LLM
“Does this user belong to at least one of these roles?”
“How can I verify a user's role membership against a list of role ids?”
Tell an agent
Check whether user {userId} has any of the roles {roleIds}.
Verify {userId} is assigned one of {roleIds}.
GET /api/v1/roles/{roleid} Get a role by its id · Load role by role ID #
Ask an LLM
“How do I look up a single role by id on the v1 API?”
“Can I include the child roles when fetching one role?”
Tell an agent
Get role {roleid}.
Fetch role {roleid} with its child roles set to {loadChildrenRoles}.
PUT /api/v1/roles/{roleid} Replace an existing role's settings · Update a role #
Ask an LLM
“How do I rename a role or move it under a different parent?”
“Does updating a role overwrite fields I leave out of the request?”
Tell an agent
Rename role {roleid} to {roleName}.
Update role {roleid} as {roleName} and move it under parent {parentRoleId}.
DELETE /api/v1/roles/{roleid} Delete a role and its grants · Delete a role #
Ask an LLM
“What happens to users and permissions when I delete a role?”
“Can a deleted role be restored?”
Tell an agent destructive · confirm first
Delete role {roleid}.
Remove role {roleid} along with its permissions and user memberships.
GET /api/v1/roles/layouts List all tool-group layouts · Get all layouts #
Ask an LLM
“Which tool groups (layouts) exist in the backend?”
“What layouts could I assign to a role?”
Tell an agent
List every layout in the system.
Show all tool groups available for roles.
POST /api/v1/roles/layouts Assign layouts to a role · Save role layouts #
Ask an LLM
“How do I give a role access to certain backend tool groups?”
“Can I add several layouts to a role in one call?”
Tell an agent
Assign layouts {layoutIds} to role {roleId}.
Give role {roleId} the tool groups {layoutIds}.
DELETE /api/v1/roles/layouts Remove layouts from a role · Delete role layouts #
Ask an LLM
“How do I take tool groups away from a role?”
“Can I unassign several layouts from a role at once?”
Tell an agent destructive · confirm first
Remove layouts {layoutIds} from role {roleId}.
Revoke tool groups {layoutIds} from role {roleId}.
GET /api/v1/roles/{roleId}/layouts List the layouts assigned to a role · Find role layouts #
Ask an LLM
“Which tool groups does this role currently have?”
“What backend layouts are attached to a given role?”
Tell an agent
Show the layouts assigned to role {roleId}.
List tool groups for role {roleId}.
GET /api/v1/roles/users/{userIdOrEmail} List the roles a user holds · Load user roles #
Ask an LLM
“Which roles does a given user have?”
“Can I look up a user's roles by email address?”
Tell an agent
List the roles for user {userIdOrEmail}.
Show what roles {userIdOrEmail} is in.
GET /api/v1/roles/{roleid}/rolehierarchyanduserroles Load a role's hierarchy and user roles · Load users and roles by role ID #
Ask an LLM
“How do I see a role's hierarchy together with the user roles under it?”
“Can I filter a role's hierarchy and user roles by name?”
Tell an agent
Load the role hierarchy and user roles for {roleid}.
Show hierarchy and user roles under {roleid} filtered by {name}.
GET /api/v1/roles/{roleid}/users List users directly granted a role · Get the users directly granted a role #
Ask an LLM
“Who are the users directly assigned to this role?”
“Does the role member list include users who inherit it through the hierarchy?”
Tell an agent
List the users directly granted role {roleid}.
Show page {page} of role {roleid} members matching {filter}.
DELETE /api/v1/roles/{roleid}/users Remove users from a role in bulk · Remove users from a role #
Ask an LLM
“How do I take several users out of a role at once?”
“What happens if some of the users in a bulk role removal aren't members?”
Tell an agent destructive · confirm first
Remove users {userIds} from role {roleid}.
Revoke the direct membership of {userIds} in role {roleid}.
GET /api/v1/roles/_search Search roles by name, key or id · Search Roles #
Ask an LLM
“How do I search for roles whose name matches some text?”
“Can a role search include workflow roles and user roles?”
Tell an agent
Search roles named like {searchName}.
Find roles with key {searchKey}, including workflow roles set to {includeWorkflowRoles}.

Documentation

📖
Documentation
https://dev.dotcms.com/docs/build/apis/api-basics/rest-apis
📖
APIReference
https://dev.dotcms.com/docs/build/apis/rest-apis/api-playground

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/dotcms/refs/heads/main/openapi/dotcms-roles-api-openapi.yml

Other Resources

🔗
DeveloperPortal
https://dev.dotcms.com/
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/dotcms/refs/heads/main/errors/dotcms-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/dotcms/refs/heads/main/data-model/dotcms-data-model.yml
🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/dotcms/refs/heads/main/conventions/dotcms-conventions.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/dotcms:dotcms-roles-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

dotcms-roles-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: dotCMS REST Roles API
  version: '3'
  description: User role and permission management
servers:
- url: /
  description: dotCMS Server
tags:


# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dotcms/refs/heads/main/openapi/dotcms-roles-api-openapi.yml