Role REST API

In the following sections, all partial URLs are relative to IQ Server's base URL, and we issue requests using the cURL tool. Also, all request/response bodies are JSON content (formatted here for readability).

Get roles

Roles can be retrieved by making an HTTP GET request to

GET /api/v2/roles

For example

curl -u admin:admin123 'http://localhost:8070/api/v2/roles'

gives

{
  "roles": [
    {
      "id": "1b92fae3e55a411793a091fb821c422d",
      "name": "System Administrator",
      "description": "Manages system configuration and users."
    },
    {
      "id": "b9646757e98e486da7d730025f5245f8",
      "name": "Policy Administrator",
      "description": "Manages all organizations, applications, policies, and policy violations."
    },
    {
      "id": "1cddabf7fdaa47d6833454af10e0a3ef",
      "name": "Owner",
      "description": "Manages assigned organizations, applications, policies, and policy violations."
    },
    {
      "id": "1da70fae1fd54d6cb7999871ebdb9a36",
      "name": "Developer",
      "description": "Views all information for their assigned organization or application."
    },
    {
      "id": "2cb71b3468d649789163ea2e212b541e",
      "name": "Application Evaluator",
      "description": "Evaluates applications and views policy violation summary results."
    },
    {
      "id": "90c7c98683b4471cb77a916744540bcc",
      "name": "Component Evaluator",
      "description": "Evaluates individual components and views policy violation results for a specified application."
    }
  ]
}

Role Management APIs

The Role Management APIs provide endpoints to create, view, update, and delete custom roles in IQ Server. These APIs allow administrators to define new roles, configure permissions, and control which actions users and groups can perform within the system. Built-in roles are read-only and cannot be modified or deleted. These APIs extend the existing Role REST API by enabling full programmatic management of custom role definitions.

Permissions Required

Get All Roles

Retrieve all roles currently configured in IQ Server.

GET /api/v2/roles

Example:

curl -u admin:admin123 -X GET http://localhost:8070/api/v2/roles

Get a Specific Role

Retrieve details for a specific role by ID.

GET /api/v2/roles/{roleId}

Example:

curl -u admin:admin123 -X GET http://localhost:8070/api/v2/roles/1da70fae1fd54d6cb7999871ebdb9a36

Get the Template for Creating a New Role

Retrieve the JSON structure and available permission categories used for creating a new custom role.

GET /api/v2/roles/new

Example:

curl -u admin:admin123 -X GET http://localhost:8070/api/v2/roles/new

Note All permissions in the template are returned with "allowed": false by default. Set "allowed": true for any permissions you want to enable in the new role.

Create a New Role

Create a new custom role using the role template as a guide.

POST /api/v2/roles

Example:

curl -u admin:admin123 -X POST http://localhost:8070/api/v2/roles \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Role",
    "description": "Test description",
    "permissionCategories": [
      {
        "displayName": "IQ",
        "permissions": [
          { "id": "READ", "allowed": true },
          { "id": "WRITE", "allowed": true }
        ]
      },
      {
        "displayName": "Remediation",
        "permissions": [
          { "id": "WAIVE_POLICY_VIOLATIONS", "allowed": true }
        ]
      }
    ]
  }'

Note Returns 400 Bad Request if the payload format is invalid or contains unsupported permissions. Returns 409 Conflict if a role with the same name already exists.

Update an Existing Role

Update an existing custom role to modify its name, description, or permissions.

PUT /api/v2/roles/{roleId}

Example:

curl -u admin:admin123 -X PUT http://localhost:8070/api/v2/roles/{roleId} \
  -H "Content-Type: application/json" \
  -d '{
    "id": "{roleId}",
    "name": "Updated Role",
    "description": "Updated description with new permissions",
    "permissionCategories": [
      {
        "displayName": "IQ",
        "permissions": [
          { "id": "READ", "allowed": true },
          { "id": "ADD_APPLICATION", "allowed": true },
          { "id": "EVALUATE_APPLICATION", "allowed": true },
          { "id": "WRITE", "allowed": false }
        ]
      },
      {
        "displayName": "Administrator",
        "permissions": [
          { "id": "VIEW_ROLES", "allowed": true }
        ]
      }
    ]
  }'

Note Returns 404 Not Found if the specified role does not exist.

Delete an Existing Role

Delete an existing custom role.

When deleted, all member assignments associated with that role are automatically removed.

DELETE /api/v2/roles/{roleId}

Example:

curl -u admin:admin123 -X DELETE http://localhost:8070/api/v2/roles/{roleId}

Note Returns 404 Not Found if the role ID is invalid. Returns 400 Bad Request if the role is a built-in system role.

Role Management Behavior

The following restrictions apply when managing roles through these APIs:

• Built-in roles (for example, System Administrator, Policy Administrator, Owner, Developer, Application Evaluator, Component Evaluator, and Legal Reviewer) cannot be modified or deleted.

• Custom roles must have unique names and cannot include system-level permissions such as Edit System Configuration and Users or Edit Custom Roles.

• The builtIn field is read-only and ignored in POST and PUT requests.

Example Use Case

To create a read-only “Compliance Reviewer” role:

curl -u admin:admin123 -X POST http://localhost:8070/api/v2/roles \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Compliance Reviewer",
    "description": "Read-only access for compliance audits",
    "permissionCategories": [
      {
        "displayName": "IQ",
        "permissions": [
          {"id": "READ", "allowed": true}
        ]
      }
    ]
  }'

Note Returns 201 Created on success.

Search results

No results found