API reference / Provisioning API / Role specification and examples

Role specification and examples

Role specification

These are the required parameters when you create a new custom role in both a domain or a reseller plan:

Parameter	Description
`name^*required`	The new custom role name.
`description`	An optional description for the role.
`policies`	The policies of the new role. Note that a role must have at least one policy when no applications are provided.
`applications`	The applications available for the role. This list can be empty ("[]").
`resourceIds`	A JSON object with the resource type and a list of resources IDs. Each resource ID instance takes a name plus an integer array. The name is not really important and only exists to provide a clearer way to describe the role. Each entry resource ID list can be empty.
`finderName`	The role default finder, if any.
`defaultApplicationName`	The required application to use as the default one. The default application name must be among the role applications specified. A default application name is not required when the policies list is empty (a missing registry key is interpreted as an empty list.)

Only the name is actually required. If you define a role and give it a name only, a role with all the available policies, applications, and resources will be created.

There are some fields that will be retrieved after a role GET (full) request. Currently, these parameters cannot be changed through the API, but can be requested:

Parameter	Description
`alertPermissions`	The list of permissions that a role has over alerts.
`defVault`	The default vault (querying priority level) defined for the role.
`maxVault`	The maximum vault defined to be used in the role.

Using the defVault and maxVault parameters

Admin users need some additional permissions in order to use the defVault and maxVault parameters. Please contact us if you need to use these parameters and we will grant the required permissions to your user.

Include all available entities

The resource ID list, policies, and applications can be provisioned using "*" instead of actual values. This will be interpreted as "include all available if any". For example:

{
  "name": "test-role",
  "description": "test-role-description",
  "policies": "*" 
}

Roles without policies

A role without policies must have at least one application, or the create/update operation will fail. A default application name is not required. The single value is also accepted, like in the "policies" entry, and will be interpreted as a list with a single value. These two examples are equivalent:

{
  "name": "test-role",
  "applications": ["test1"]
}

{
  "name": "test-role",
  "applications": "test1"
}

The following request would not be accepted, since there are not any applications. It would only be correct if the operation is an update and the role already has the test1 application.

{
  "name": "test-role",
  "applications": [],
  "defaultApplicationName": "test1"
}

Complete example

This is an example including all the parameters:

{
  "name": "test-role",
  "description": "test-role-description",
  "applications": ["my-custom-app","another-app"],
  "defaultApplicationName": "my-custom-app",
  "policies": "*",
  "resourceIds": {
    "dashboard": [501]
  }
}

Include all available resources

Including resources by default is a little trickier. Creating a role specifying the available resources can be done sending a body like the following:

{
  "name": "test-role",
  "policies": "*",
  "resourceIds": {
    "dashboard": [501] 
  }
}

Note that the key "dashboard" is arbitrary and has no real meaning, that is, we could add any value we want.

Or you can include everything like this:

{
  "name": "test-role"
  "policies": "*",
  "resourceIds": {
    "*": [] 
  }
}

Request examples

Basic role creation

This will create a new role custom with all the available default values (for example, with all available policies).

`POST /domain/{domainName}/roles`

{
  "name": "my-new-role",
  "policies": "*"
}

Detailed role creation

More options can be included when creating a new custom role, for example, the policies and a description.

`POST /domain/{domainName}/roles`

{
  "name": "my-new-role",
  "description": "this is my new role",
  "policies": [ "policy.alerts_config.view" ]
}

Note that the policy must exist and be available in the domain (that is, for the Admin role).

Create requirements

Creating a new custom role requires some policies to be applied, failing to do this results in an error. For example, this request would fail:

`POST /domain/{domainName}/roles`

{
  "name": "my-new-role",
  "description": "this is my new role",
  "policies": []
}

While the following should work:

`POST /domain/{domainName}/roles`

{
  "name": "my-new-role",
  "description": "this is my new role",
  "applications: ["default-app"],
  "policies": []
}

Resource IDs

The resource IDs are matched as a key-value map and will be flattened at the server side (meaning only the inner collections IDs are relevant for the service). The following two requests are equivalent:

{
  "name": "my-new-role",
  "description": "this is my new role"
  "resourceIds": {
    "dashboard": [501],
    "test": [800]
  }
}

{
  "name": "my-new-role",
  "description": "this is my new role"
  "resourceIds": {
    "dashboard": [501,800]
  }
}

Updating values

If we have created the following role:

`POST /domain/{domainName}/roles`

{
  "name": "test-role",
  "description": "test-role-description",
  "applications": "*",
  "defaultApplicationName": "my-custom-app"
}

And we want to remove the default application, we can use the following:

`PUT /domain/{domainName}/roles/{roleName}`

{
  "defaultApplicationName": ""
}

Download as PDF