Access Control (REST) API - Roles
This section includes REST APIs for working with Access Control Role tasks.
Get All Roles - GET /Roles
Get details of all roles.
Notice
The ‘Manage Roles’ or ‘Manage Users’ permission is required to execute this API.
Usage:
GET /Users and get details of all roles
PUT /Roles/{id} and update role details
URL
/cxrestapi/auth/Roles
Method:
GET
Media Type (header):
Authorization: Bearer <access token value>
Accept: application/json;v=1.0
Parameters
None
Success Response:
Code: 200 Success
Error Response:
Code: 401 Unauthorized
Code: 403 Forbidden
Sample Response:
[ { "id": 1, "isSystemRole": true, "name": "Admin", "description": "Checkmarx products global administrator", "permissionIds": [ 1, 2, 3, 4, ] }, { "id": 2, "isSystemRole": true, "name": "Access Control Manager", "description": "Manages users, authentication and system settings", "permissionIds": [ 1, 2, ] }, { "id": 3, "isSystemRole": true, "name": "User Manager", "description": "Manages the users in the system", "permissionIds": [ 1 ] }, { "id": 4, "isSystemRole": true, "name": "SAST Scanner", "description": "This role grants permissions to create and manage projects, and run scans", "permissionIds": [ 7, 8, 10, ] }, { "id": 5, "isSystemRole": true, "name": "SAST Reviewer", "description": "This role grants \"read only\" permissions to view scan results and generate reports", "permissionIds": [ 14, 15, 16, ] } ]
Notes:
Retrieves details of all roles. Permission Id (permissionIds) is used in the Permissions API. If the request fails, it returns an error response.
Create New Role - POST /Roles
Create a new role.
Notice
The ‘Manage Roles’ permission is required to execute this API.
Usage:
POST /Roles and create a new role
GET /Users and get details of all roles
URL
/cxrestapi/auth/Roles
Method:
POST
Media Type (header):
Authorization: Bearer <access token value>
Content-Type: application/json;v=1.0
Parameters
createRoleModel=[body]: Specifies the role’s details
name=[string] - Role name
description=[string] - Role description
permissionIds=[integer] - Role related permission Ids
Success Response:
Code: 201 Success (returns location of the created role in the response header)
Error Response:
Code: 400 Bad Request
Code: 401 Unauthorized
Code: 403 Forbidden
Sample Response:
no content
Notes:
Returns the location of the created role in the response header. If the request fails, it returns an error response.
Get Role by Id - GET /Roles/{id}
Get details of a role.
Notice
The ‘Manage Roles’ or ‘Manage Users’ permission is required to execute this API.
Usage:
GET /Roles/{id} and get details of a role
PUT /Roles/{id} and update role details
URL
/cxrestapi/auth/Roles/{id}
Method:
GET
Media Type (header):
Authorization: Bearer <access token value>
Accept: application/json;v=1.0
Parameters
Required:
id=[integer] – Unique Id of the Role
Success Response:
Code: 201 Success
Error Response:
Code: 400 Bad Request
Code: 401 Unauthorized
Code: 403 Forbidden
Code: 404 Not Found
Sample Response:
{ "id": 5, "isSystemRole": true, "name": "SAST Reviewer", "description": "This role grants \"read only\" permissions to view scan results and generate reports", "permissionIds": [ 14, 15, 16, 18, 23 ] }
Notes:
Retrieves role details according to the role Id. If the request fails, it returns an error response.
Update a Role - PUT /Roles/{id}
Update role details according to Role Id.
Notice
The ‘Manage Roles’ permission is required to execute this API.
Usage:
GET /Roles/{id} and get details of a role
PUT /Roles/{id} and update role details
URL
/cxrestapi/auth/Roles/{id}
Method:
PUT
Media Type (header):
Authorization: Bearer <access token value>
Content-Type: application/json;v=1.0
Parameters
Required:
id=[integer] - Unique Id of the role
updateRoleModel=[body]: Specifies the role’s details
name=[string] - Role name
description=[string] - Role description
permissionIds=[integer] - Role related permission Ids
Success Response:
Code: 204 Success
Error Response:
Code: 400 Bad Request
Code: 401 Unauthorized
Code: 403 Forbidden
Code: 404 Not found
Sample Response:
no content
Notes:
Updates the role details according to role Id. Once the request is successful, it does not return any content. If the request fails, it returns an error response.
Delete a Role – DELETE /Roles/{id}
Delete a role according to Role Id.
Notice
The ‘Manage Roles’ permission is required to execute this API.
Usage:
GET /Users and get details of all roles
DELETE /Roles/{id} and delete a role
URL
/cxrestapi/auth/Roles/{id}
Method:
DELETE
Media Type (header):
Authorization: Bearer <access token value>
Content-Type: application/json;v=1.0
Parameters
Required:
id=[integer] – Unique Id of the role
Success Response:
Code: 204 Success
Error Response:
Code: 400 Bad Request
Code: 401 Unauthorized
Code: 403 Forbidden
Code: 404 Not found
Sample Response:
no content
Notes:
Deletes the role details according to role Id. Once the request is successful, it does not return any content. If the request fails, it returns an error response.