Skip to main content

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:

  1. GET /Users and get details of all roles

  2. 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:

  1. POST /Roles and create a new role

  2. 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:

  1. GET /Roles/{id} and get details of a role

  2. 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:

  1. GET /Roles/{id} and get details of a role

  2. 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:

  1. GET /Users and get details of all roles

  2. 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.