Introduction

TIP

View the Security Module API Reference

The Security Module APIs give programmatic access to a portal's role-based security model: the security roles that grant permissions to users, the categories those roles are grouped under, and the dynamic assignment filters that decide which users and OUs a role is automatically applied to.

All endpoints sit under https://{corpname}.csod.com/services/api/x/security-module/v1/.

Resource model

The API is organised into two families, each with its own section in the reference.

Family	Manages
Security Roles	Reading a single role, searching roles, and reading a role's dynamic assignment filters (OU and user)
Security Categories	Creating, reading, searching, updating and deleting the categories that roles are grouped under

A security role belongs to exactly one category (categoryID). Categories are a small, flat lookup of names, so the two families are usually used together: list the categories to find the one you want, then search roles within it.

Roles are read-only here

This API reads roles and their dynamic assignments; it does not create or modify roles. Writes are available on categories only. Use the Cornerstone admin UI to author roles.

Reading data

The role search, category search and role dynamic-assignment endpoints are offset-paged. You choose a window of records with startRecord and endRecord and sort it with sortBy and sortDirection:

GET /services/api/x/security-module/v1/roles?startRecord=1&endRecord=20

Every paged response carries a totalRecords count alongside its records, so you can tell how many pages remain:

{
  "totalRecords": 143,
  "roles": []
}

totalRecords is the full count that matches your filter, ignoring the paging window. See Pagination for how the window and sort parameters work, including the dynamic-assignments endpoint, which pages its OU and user filters independently.

Single-record reads (GET .../roles/id/{roleId}, GET .../categories/id/{categoryId}) return the record directly and respond 404 when nothing matches the id.

Writing data

Only categories are writable:

• Create with POST v1/categories. The response carries the new category and its URI in the Location header.
• Update a category's name with PUT v1/categories (the body carries the categoryId and the new categoryName).
• Delete with DELETE v1/categories/{categoryId}.

See Quick Start: Categories for the full lifecycle.

Errors

A failed request returns a plain error body with a single human-readable value message:

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

Branch your integration on the HTTP status code; the value text is for humans and may change. A read against an id that does not exist returns 404; an invalid create, update or delete payload returns 400.

Scopes and permissions

Every request needs an OAuth 2.0 scope on the application and the Security Module security permission on the linked user account. Scopes follow a security_<resource>:<operation> shape, and each operation maps to a unique scope:

Operation	Method & Path	Scope
Get role by id	GET v1/roles/id/{roleId}	security_role:read
Search roles	GET v1/roles	security_role:search
Get role dynamic assignments	GET v1/roles/{roleId}/dynamicAssignments	security_roleassignments:read
Get category by id	GET v1/categories/id/{categoryId}	security_category:read
Search categories	GET v1/categories	security_category:search
Create category	POST v1/categories	security_category:create
Update category	PUT v1/categories	security_category:update
Delete category	DELETE v1/categories/{categoryId}	security_category:delete

Every endpoint also requires the Security Module permission on the calling user account. A caller that lacks it is refused with 403. Each endpoint is listed individually in List of Scopes and Security Permissions for APIs.

Throttling

Every endpoint is throttled at 1,000 requests per minute at the URI level. See Throttling for the per-endpoint table, and the Throttling section of the Getting Started guide for guidance on handling throttling responses.