# Create

To create a new role you need to execute a **POST** request against the **/roles** endpoint.

The following fields need to be set:

* **name ->** internal <mark style="color:red;">**unique**</mark> name to reference the role in [rooms](https://docs.digitalsamba.com/reference/rest-api/rooms) and [tokens](https://docs.digitalsamba.com/reference/rest-api/tokens)
* **display\_name ->** the display name people will see visually inside the participants list
* **permissions ->** a JSON object of the [permission names](https://docs.digitalsamba.com/reference/rest-api/roles-and-permissions/permissions) this role is allowed to have. Allowed permissions have **true** as a value. For role sensitive permissions like **remote\_muting** you can additionally specify an array with the role names which the participant is allowed to operate on.\
  For example you can make a Speaker be allowed to remote mute an Attendee, but not remote mute a Moderator. If you don't specify the array (and just put **true**), that means the participant is allowed to operate on all roles (current and future). That gives you full flexibility.
* **description** (optional) -> text description if you want to add some explanations

{% hint style="warning" %}
Creating a role doesn't immediately assign it to any rooms. You need to specify the available roles inside a room during [room creation](https://docs.digitalsamba.com/reference/rooms/create#3.-request-a-room-with-moderator-speaker-and-attendee-roles). If all of your rooms will have the same roles it may be easier for you to set these roles in the default [team settings](https://docs.digitalsamba.com/reference/rest-api/default-room-settings), so all rooms will inherit the same default roles.
{% endhint %}

#### Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request POST \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1/roles \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{
     "name": "custom", 
     "display_name": "Custom", 
     "permissions": {
        "start_session": true, 
        "remote_muting": ["speaker", "attendee"],
        "raise_hand": true
     } 
  }'
```

{% endtab %}

{% tab title="Java" %}

```java
import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.util.Base64;
import java.util.Map;

String TEAM_ID = "YOUR_TEAM_ID";
String DEVELOPER_KEY = "YOUR_DEVELOPER_KEY";
String authorizationHeader = "Bearer " + Base64.getEncoder().encodeToString((TEAM_ID + ":" + DEVELOPER_KEY).getBytes());

Map<String, Object> data = Map.of(
  "name", "custom",
  "display_name", "Custom",
  "permissions", Map.of( "start_session", true,
		         "remote_muting", new String[] {"speaker", "attendee"},
		         "raise_hand", true
		 )
);
String jsonData = new ObjectMapper().writeValueAsString(data);

HttpRequest request = HttpRequest.newBuilder()
  .POST(HttpRequest.BodyPublishers.ofString(jsonData))
  .uri(new URI("https://api.digitalsamba.com/api/v1/roles"))
  .header("Authorization", authorizationHeader)
  .header("Content-Type", "application/json")
  .build();

HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, BodyHandlers.ofString());

System.out.println("Status code: " + response.statusCode());
System.out.println("Body: " + response.body());
```

{% endtab %}
{% endtabs %}

#### Response (200 OK)

```json
{
    "id": "2d9448b9-d9ee-4102-b31a-f83ab4af2af8",
    "name": "custom",
    "display_name": "Custom",
    "description": null,
    "default": false,
    "created_at": "2023-03-24T13:32:05Z",
    "updated_at": "2023-03-27T13:46:22Z",
    "permissions": {
        "ask_remote_unmute": false,
        "broadcast": false,
        "end_session": false,
        "general_chat": false,
        "manage_broadcast": false,
        "manage_roles": false,
        "manage_screenshare": false,
        "raise_hand": true,
        "recording": false,
        "remote_muting": [
            "speaker",
            "attendee"
        ],
        "remove_participant": false,
        "screenshare": false,
        "start_session": true
    }
}
```