# 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

| Operation                                   | Required Permission                    |
| ------------------------------------------- | ------------------------------------- |
| View roles                                  | `View All Roles`                      |
| Create, update, delete roles, or view the role template | `Edit Custom Roles`                    |

## 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