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.

In this section: