# Role

{% hint style="info" %}
Managing roles is the initial step in implementing[ role-based access](https://docs.datasentinel.io/manual/features/other-features/role-based-access)
{% endhint %}

To use the Role API, it's necessary to generate an access token.

{% content-ref url="access-token" %}
[access-token](https://docs.datasentinel.io/manual/implementation/platform-usage/api-reference/access-token)
{% endcontent-ref %}

{% hint style="info" %}
A comprehensive toolkit, with practical usage examples, is accessible on [GitHub](https://github.com/datasentinel/datasentinel_toolkit).

This  toolkit comes pre-installed as a default component within the on-premises platform, located at `/datasentinel/soft/datasentinel_toolkit`.
{% endhint %}

## **Role**

## Add

<mark style="color:green;">`POST`</mark> `https://<<platform-server>>/ds-api/roles/{role}`

Create a New Role

#### Path Parameters

| Name                                   | Type   | Description |
| -------------------------------------- | ------ | ----------- |
| role<mark style="color:red;">\*</mark> | String | Role Name   |

#### Headers

| Name                                         | Type   | Description            |
| -------------------------------------------- | ------ | ---------------------- |
| user-token<mark style="color:red;">\*</mark> | String | Generated Access Token |

#### Request Body

| Name                                     | Type  | Description      |
| ---------------------------------------- | ----- | ---------------- |
| access<mark style="color:red;">\*</mark> | Array | Array of Filters |

**Response**

{% tabs %}
{% tab title="201: Created " %}

```json
{
  "status": "Role name <<role>> created successfully"
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="409: Conflict " %}

{% endtab %}

{% tab title="500: Internal Server Error Internal error" %}

{% endtab %}
{% endtabs %}

The JSON array structure should adhere to the following format:

```json
"access": [
 {
    "filters": [
        {"tag": "tag_name", "value": "tag_value"},
        {"tag": "another_tag", "value": "another_value"},
        ...
    ]
 }
]
```

{% hint style="info" %}
It's important to note that the specified tags must already exist and be linked to one or more instances.
{% endhint %}

```json
// Example: 
// Establish a role-based access that exclusively applies to instances 
// categorized as "production" 
// AND situated within the "London" datacenter.
"access": [
 {
    "filters":
      [
              {"tag": "environment", "value": "production"},
              {"tag": "datacenter", "value": "london"}
      ]
 }
]
```

```json
// Example:
// Establish a role-based access that encompasses instances 
// categorized as either "development" OR "uat"
"access": [
  {
    "filters":
      [
        { "tag": "environment", "value": "development" }
      ]
  },
  {
    "filters":
      [
        { "tag": "environment", "value": "uat" }
      ]
  },
]

```

{% hint style="info" %}
You can combine multiple AND/OR conditions within the JSON array
{% endhint %}

## Display

<mark style="color:blue;">`GET`</mark> `https://<<platform-server>>/ds-api/roles/{role}`

Display Role Attributes

#### Path Parameters

| Name                                   | Type   | Description |
| -------------------------------------- | ------ | ----------- |
| role<mark style="color:red;">\*</mark> | String | Role Name   |

#### Headers

| Name                                         | Type   | Description            |
| -------------------------------------------- | ------ | ---------------------- |
| user-token<mark style="color:red;">\*</mark> | String | Generated Access Token |

**Response**

{% tabs %}
{% tab title="200: OK " %}
{% code title="Example" %}

```json
{
"name": "myRole",
"access": [
    {
        "filters": [
            {
                "tag": "pg_instance",
                "value": "51.15.233.24@agentLess6"
            }
        ]
    },
    {
        "filters": [
            {
                "tag": "pg_instance",
                "value": "51.158.104.206@agentLess11"
            }
        ]
    }
  ]
}

```

{% endcode %}
{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}

{% tab title="500: Internal Server Error Internal error" %}

{% endtab %}
{% endtabs %}

## Assigned Users

<mark style="color:blue;">`GET`</mark> `https://<<platform-server>>/ds-api/roles/{role}/users`

Display the users assigned to a specific role

#### Path Parameters

| Name                                   | Type   | Description |
| -------------------------------------- | ------ | ----------- |
| role<mark style="color:red;">\*</mark> | String | Role Name   |

#### Headers

| Name                                         | Type   | Description            |
| -------------------------------------------- | ------ | ---------------------- |
| user-token<mark style="color:red;">\*</mark> | String | Generated Access Token |

**Response**

{% tabs %}
{% tab title="200: OK " %}
{% code title="Example" %}

```json
[
  {
      "id": 70,
      "login": "username",
      "email": "userName@myCompany.com",
      "profile": "data admin",
      "privilege": "admin",
      "role": "myRole",
      "live_360": 1
  }
]
```

{% endcode %}
{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}

{% tab title="500: Internal Server Error Internal error" %}

{% endtab %}
{% endtabs %}

## Replace

<mark style="color:orange;">`PUT`</mark> `https://<<platform-server>>/ds-api/roles/{role}`

Replace existing role

#### Path Parameters

| Name                                   | Type   | Description |
| -------------------------------------- | ------ | ----------- |
| role<mark style="color:red;">\*</mark> | String | Role Name   |

#### Headers

| Name                                         | Type   | Description            |
| -------------------------------------------- | ------ | ---------------------- |
| user-token<mark style="color:red;">\*</mark> | String | Generated Access Token |

#### Request Body

| Name                                     | Type  | Description      |
| ---------------------------------------- | ----- | ---------------- |
| access<mark style="color:red;">\*</mark> | Array | Array of Filters |

**Response**

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "status": "Role name <<role>> updated successfully"
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}

{% tab title="500: Internal Server Error Internal error" %}

{% endtab %}
{% endtabs %}

<mark style="color:red;">`DELETE`</mark> `https://<<platform-server>>/ds-api/roles/{role}`

Delete Role

#### Path Parameters

| Name                                   | Type   | Description |
| -------------------------------------- | ------ | ----------- |
| role<mark style="color:red;">\*</mark> | String | Role Name   |

#### Headers

| Name                                         | Type   | Description            |
| -------------------------------------------- | ------ | ---------------------- |
| user-token<mark style="color:red;">\*</mark> | String | Generated Access Token |

**Response**

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "status": "Role name <<role>> deleted successfully"
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}

{% tab title="500: Internal Server Error Internal error" %}

{% endtab %}
{% endtabs %}

## Roles

## Display

<mark style="color:blue;">`GET`</mark> `https://<<platform-server>>/ds-api/roles`

Display All Roles

#### Headers

| Name                                         | Type   | Description            |
| -------------------------------------------- | ------ | ---------------------- |
| user-token<mark style="color:red;">\*</mark> | String | Generated Access Token |

**Response**

{% tabs %}
{% tab title="200: OK " %}
{% code title="Example" %}

```json
[
  {
      "name": "myRole",
      "access": [
          {
              "filters": [
                  {
                      "tag": "pg_instance",
                      "value": "51.15.233.24@agentLess6"
                  }
              ]
          },
          {
              "filters": [
                  {
                      "tag": "pg_instance",
                      "value": "51.158.104.206@agentLess11"
                  }
              ]
          }
      ]
  },
  {
      "name": "testrole",
      "access": [
          {
              "filters": [
                  {
                      "tag": "pg_version",
                      "value": "11.8"
                  },
                  {
                      "tag": "pg_instance",
                      "value": "51.15.233.24@agentLess6"
                  }
              ]
          }
      ]
  }
]
```

{% endcode %}
{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}

{% tab title="500: Internal Server Error Internal error" %}

{% endtab %}
{% endtabs %}