Quick Start: Security roles

TIP

View the Security Module API Referenceopen in new window

Security roles grant permissions to users and are grouped under categories. This API reads roles; it does not create or change them. There are three things you can do: read one role by its id, search roles with a filter, and read a role's dynamic assignment filters.

Step 1: Search for roles

GET v1/roles returns a page of roles with a totalRecords count. Narrow the result with the optional filters below, and page it with startRecord/endRecord (see Pagination).

Parameter	Type	Default	Description
`searchText`	string		Free-text filter matched against role titles.
`parentId`	integer	`0`	Restrict the search to children of this parent role id.
`roleRef`	string		Filter by external reference id.
`includeInactive`	boolean	`false`	When `true`, inactive roles are included.
`returnHierarchy`	boolean	`false`	When `true`, the results resolve the role hierarchy.
`startRecord`	integer	`1`	1-based index of the first record to return.
`endRecord`	integer	`20`	1-based index of the last record to return.
`sortBy`	integer	`1`	Column to sort by.
`sortDirection`	integer	`1`	Sort direction.

GET /services/api/x/security-module/v1/roles?searchText=admin&startRecord=1&endRecord=20
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

{
  "totalRecords": 3,
  "roles": [
    {
      "roleID": 5001,
      "title": "LMS Administrator",
      "description": "Full learning admin",
      "categoryID": 101,
      "cannotRemove": false,
      "cannotAssign": false,
      "canManage": true,
      "hasChildren": true,
      "parentId": 0,
      "isActive": true,
      "roleRef": "role-lms-admin"
    }
  ]
}

Match roles by `roleRef`, not `roleID`

roleID and categoryID are portal-specific. When you need to recognise the same role across portals or environments, filter and match on roleRef.

This search requires the security_role:search scope.

Step 2: Read a single role

Once you have a roleID, read the full record directly:

GET /services/api/x/security-module/v1/roles/id/5001
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

{
  "roleID": 5001,
  "title": "LMS Administrator",
  "description": "Full learning admin",
  "categoryID": 101,
  "cannotRemove": false,
  "cannotAssign": false,
  "canManage": true,
  "hasChildren": true,
  "parentId": 0,
  "isActive": true,
  "roleRef": "role-lms-admin"
}

An id that matches no role returns 404:

{
  "value": "Role with Id : 9999 not found!"
}

This read requires the security_role:read scope.

What the flags tell you:

cannotRemove / cannotAssign — system constraints on whether the role can be removed or assigned.
canManage — whether the calling user is allowed to manage the role.
hasChildren — whether the role has child roles. Use parentId on the search to walk down one level.
isActive — whether the role is currently active. Inactive roles are excluded from search unless you pass includeInactive=true.

Step 3: Read a role's dynamic assignments

Dynamic assignments are the OU and user filters that decide which users a role is automatically applied to. Read them for a role with:

GET /services/api/x/security-module/v1/roles/5001/dynamicAssignments?startRecord=1&endRecord=20
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

{
  "roleId": 5001,
  "ouFilters": [
    { "filterId": 11, "ouId": 42, "includeSubs": true, "typeId": 2 }
  ],
  "ouTotalRecords": 1,
  "userFilters": [
    { "filterId": 73, "userId": 9001, "includeSubs": false }
  ],
  "userTotalRecords": 1
}

OU filters apply the role to an OU (ouId) of a given type (typeId). includeSubs extends it to subordinate OUs.
User filters apply the role to a specific user (userId). includeSubs extends it to that user's subordinates.

The two collections are paged independently and each carries its own total (ouTotalRecords, userTotalRecords); see Pagination. A role id that does not exist returns 404.

This read requires the security_roleassignments:read scope.