Quick Start: Security categories

TIP

View the Security Module API Referenceopen in new window

Categories group security roles. They are a small, flat set of named buckets, and unlike roles they are fully writable through this API. This walkthrough covers the whole lifecycle: create, read, search, update and delete.

Step 1: Create a category

POST /services/api/x/security-module/v1/categories
Content-Type: application/json
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

{
  "categoryName": "Learning Admins",
  "createdBy": 1
}

categoryName is the display name of the category.
createdBy is the id of the user creating it.

On success the API responds 201 Created, returns the new category and sends its URI (v1/categories/{id}) in the Location header:

{
  "categoryID": 101,
  "categoryName": "Learning Admins",
  "createdDate": "2026-09-07T16:00:00Z",
  "createdBy": 1
}

An invalid payload returns 400. Creating a category requires the security_category:create scope.

Step 2: Read a category by id

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

{
  "categoryID": 101,
  "categoryName": "Learning Admins",
  "createdDate": "2026-09-07T16:00:00Z",
  "createdBy": 1
}

An id that matches no category returns 404:

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

This read requires the security_category:read scope.

Step 3: Search categories

GET v1/categories returns a page of categories with a totalRecords count. Filter by name with searchText and page it with startRecord/endRecord (see Pagination).

Parameter	Type	Default	Description
`searchText`	string		Free-text filter matched against category names.
`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/categories?searchText=admin&startRecord=1&endRecord=20

{
  "totalRecords": 2,
  "categories": [
    {
      "categoryID": 101,
      "categoryName": "Learning Admins",
      "createdDate": "2026-09-07T16:00:00Z",
      "createdBy": 1
    }
  ]
}

Searching requires the security_category:search scope.

Step 4: Update a category

Updating changes a category's name. The body carries the categoryId to update and the new categoryName:

PUT /services/api/x/security-module/v1/categories
Content-Type: application/json
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

{
  "categoryId": 101,
  "categoryName": "LMS Admins"
}

A successful update responds 204 No Content. An invalid payload returns 400. Updating requires the security_category:update scope.

Step 5: Delete a category

The category to delete is addressed in the path:

DELETE /services/api/x/security-module/v1/categories/101
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

A successful delete responds 204 No Content. A delete that cannot be completed returns 400. Deleting requires the security_category:delete scope.

Roles reference categories

A security role belongs to a category through its categoryID. Deleting a category that roles still point at can leave those roles without a valid category, so confirm no active role references it before deleting.