> For the complete documentation index, see [llms.txt](https://docs.ushahidi.com/v3-ushahidi-platform-rest-api-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ushahidi.com/v3-ushahidi-platform-rest-api-documentation/v3/roles.md).

# Roles

{% openapi src="/files/DFxnj85ZsASPYXzkPAko" path="/api/v3/roles" method="get" %}
[UshahidiV3.json](https://content.gitbook.com/content/tXIYKGMTeHub5C8O9fER/blobs/TC8KXqdBoVrA1ZGmo9Kk/UshahidiV3.json)
{% endopenapi %}

## add role

<mark style="color:green;">`POST`</mark> `https://ushahididocs.api.ushahidi.io/api/v3/roles`

#### Request Body

| Name          | Type    | Description                                            |
| ------------- | ------- | ------------------------------------------------------ |
| name          | String  | Name of the User                                       |
| permissions   | array   | An array containing strings of role permissions        |
| description   | String  | Role description                                       |
| display\_name | String  | The user display name                                  |
| protected     | Boolean | Set True to protect the role and false for unprotected |

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

```javascript
{
  "id": 0,
  "url": "string",
  "name": "string",
  "display_name": "string",
  "description": "string",
  "permissions": [
    true
  ],
  "allowed_priviledges": [
    "string"
  ]
}
```

{% endtab %}
{% endtabs %}

{% openapi src="/files/DFxnj85ZsASPYXzkPAko" path="/api/v3/roles/100" method="get" %}
[UshahidiV3.json](https://content.gitbook.com/content/tXIYKGMTeHub5C8O9fER/blobs/TC8KXqdBoVrA1ZGmo9Kk/UshahidiV3.json)
{% endopenapi %}

## edit role

<mark style="color:orange;">`PUT`</mark> `https://ushahididocs.api.ushahidi.io/api/v3/roles/1`

#### Request Body

| Name          | Type    | Description                                            |
| ------------- | ------- | ------------------------------------------------------ |
| display\_name | String  | Display name                                           |
| permissions   | Array   | An array containing strings of permissions             |
| description   | String  | Role description                                       |
| protected     | Boolean | Set True to protect the role and false for unprotected |

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

```javascript
{
  "id": 1,
  "url": "https://ushahididocs.api.ushahidi.io//api/v3/roles/1",
  "name": "user",
  "display_name": "test user2",
  "description": "test user description",
  "permissions": [
    "Edit their own posts",
    "Delete Their Own Posts"
  ],
  "protected": true,
  "allowed_privileges": [
    "read",
    "create",
    "update",
    "search"
  ]
}
```

{% endtab %}
{% endtabs %}

{% openapi src="/files/DFxnj85ZsASPYXzkPAko" path="/api/v3/roles/8" method="delete" %}
[UshahidiV3.json](https://content.gitbook.com/content/tXIYKGMTeHub5C8O9fER/blobs/TC8KXqdBoVrA1ZGmo9Kk/UshahidiV3.json)
{% endopenapi %}