Roles
Operations for managing roles including creation, editing, deletion, and listing roles.
This endpoint retrieves a list of roles and returns their attributes. This API does not list permissions for said roles. To receive that information, leverage the existing Get-Roles API. Note: 'role_id' refers to the immutable role ID, while 'pretty_name' refers to the display name.
Successfully retrieved roles
Metadata for the response
Unauthorized access
Unauthorized access due to lack of sufficient permissions. This includes Instance Administrator privilege escalation errors: non-admin API keys cannot assign, modify, or delete entities that have the Instance Administrator role.
Internal server error. A unified status for API communication type errors.
GET /platform/iam/v1/role HTTP/1.1
Host: api-{{fqdn}}
Accept: */*
{
"data": [
{
"role_id": "test_role_01",
"pretty_name": "Test Role Pretty Name 01",
"description": "Complete description",
"is_custom": true,
"created_by": "User 01",
"created_ts": 1661171650679,
"updated_ts": 1661171650679
},
{
"role_id": "test_role_02",
"pretty_name": "Test Role Pretty Name 02",
"description": "Complete description",
"is_custom": true,
"created_by": "User 02",
"created_ts": 1661171650679,
"updated_ts": 1661171650679
}
],
"metadata": {
"total_count": 2
}
}To identify all potential permissions that can be entered into the 'component_permissions' field, please utilize the 'GET /platform/iam/v1/role/permission-config' endpoint and utilize the 'view_name' and 'action_name' properties. Note: if you input an 'action' permission, then the relevant 'view' permission will be added for you. There will also be checks done on sub-permissions, ensuring that the main 'action' permissions are present as well. The available datasets can also be found by utilizing the 'GET /platform/iam/v1/role/permission-config' endpoint. Any dataset related permissions are not permissible in the 'component_permissions' field (an error will be thrown). The 'permissions' field in the entry for 'dataset_permissions' refers to dataset names for said dataset category.It is important to note that the 'access_all' field will only grant the role access to all datasets in said category that the API key has access to.
Role created successfully
Bad request for role create call
Unauthorized access
Unauthorized access due to lack of sufficient permissions. This includes Instance Administrator privilege escalation errors: non-admin API keys cannot assign, modify, or delete entities that have the Instance Administrator role.
Internal server error. A unified status for API communication type errors.
POST /platform/iam/v1/role HTTP/1.1
Host: api-{{fqdn}}
Content-Type: application/json
Accept: */*
Content-Length: 247
{
"request_data": {
"component_permissions": [
"rules_action",
"wf_verdict_change"
],
"dataset_permissions": [
{
"category": "Lookup",
"access_all": true,
"permissions": []
}
],
"pretty_name": "CustomRoleName",
"description": "A custom role with specific permissions"
}
}{
"data": {
"message": "role_id test_role01 created successfully."
}
}Delete an existing Role
Full role id of the custom role
Role deleted successfully
Bad request for role delete call
Unauthorized access
Unauthorized access due to lack of sufficient permissions. This includes Instance Administrator privilege escalation errors: non-admin API keys cannot assign, modify, or delete entities that have the Instance Administrator role.
Internal server error. A unified status for API communication type errors.
DELETE /platform/iam/v1/role/{role_id} HTTP/1.1
Host: api-{{fqdn}}
Accept: */*
{
"data": {
"message": "role_id test_role01 deleted successfully."
}
}Returns the current list of permissions available for the specified tenant. Each permission includes:
name: Display name of the permission as shown in the UI.
view_name: Permission key for the "View" option, used in role creation APIs.
action_name: Permission key for the "View/Edit" option, used in role creation APIs.
Intended use: Use this endpoint to identify the correct permission keys corresponding to the display names visible in the UI. Note - The response mirrors how permissions are organized and displayed in the UI (by category and subcategory).
Successfully retrieved permission configs
Metadata for the response
Unauthorized access
Unauthorized access due to lack of sufficient permissions. This includes Instance Administrator privilege escalation errors: non-admin API keys cannot assign, modify, or delete entities that have the Instance Administrator role.
Internal server error. A unified status for API communication type errors.
GET /platform/iam/v1/role/permission-config HTTP/1.1
Host: api-{{fqdn}}
Accept: */*
{
"data": {
"rbac_permissions": [
{
"category_name": "Dashboards & Reports",
"sub_categories": [
{
"sub_category_name": null,
"permissions": [
{
"name": "Dashboards",
"view_name": "dashboard_view",
"action_name": "dashboard_action",
"sub_permissions": []
},
{
"name": "Reports",
"view_name": "reports_view",
"action_name": "reports_action",
"sub_permissions": []
}
]
}
]
},
{
"category_name": "Investigation & Response",
"sub_categories": [
{
"sub_category_name": "Search",
"permissions": [
{
"name": "Query Center",
"view_name": "investigation_query_view",
"action_name": "investigation_query_action",
"sub_permissions": []
}
]
},
{
"sub_category_name": "Response",
"permissions": [
{
"name": "Action Center",
"view_name": "actions_center",
"action_name": "actions_center_action",
"sub_permissions": [
{
"action_name": "isolate",
"name": "Isolate"
},
{
"action_name": "quarantine",
"name": "Quarantine"
}
]
}
]
}
]
}
],
"datasetGroups": [
{
"datasets": [
"alerts",
"cases",
"endpoints",
"incidents"
],
"dataset_category": "System"
},
{
"datasets": [],
"dataset_category": "Lookup"
}
]
}
}Last updated
Was this helpful?