# Roles

## Introduction

`Roles` are used to manage `Permissions` in intratool.

The binding of `Permissions` to a `Role` is done by a pivot table called `permission_role`, in which each `Permission` of the unique `Role` is assigned.

Those `Roles` will then get assigned to a [Department](https://docs.api.intratool.de/api-reference/departments) so that every member of a [Department](https://docs.api.intratool.de/api-reference/departments) has the same `Permissions`.

## Model Definition

### Alias

`role`

### Relations

| Key                               | Relation                                                               | Type            | Relation Field(s)  |
| --------------------------------- | ---------------------------------------------------------------------- | --------------- | ------------------ |
| `user`                            | [User](https://docs.api.intratool.de/api-reference/users)              | Belongs to      | `user_id`          |
| `department`                      | [Department](https://docs.api.intratool.de/api-reference/departments)  | Belongs to      | `department_id`    |
| `folder`                          | [Folder](https://docs.api.intratool.de/api-reference/folders)          | Belongs to      | `folder_id`        |
| `departments`                     | [Departments](https://docs.api.intratool.de/api-reference/departments) | Belongs to many | Intermediate table |
| `infoboardDepartments`            | [Departments](https://docs.api.intratool.de/api-reference/departments) | Belongs to many | Intermediate table |
| `quickTaskAssignmentsDepartments` | [Departments](https://docs.api.intratool.de/api-reference/departments) | Belongs to many | Intermediate table |
| `permissions`                     | [Permissions](https://docs.api.intratool.de/api-reference/permissions) | Belongs to many | Intermediate table |
| `users`                           | [Users](https://docs.api.intratool.de/api-reference/users)             | Has many        | `users.role_id`    |

## List

Get a list of all `Roles`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/roles`

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/roles', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 2,
    "name": "Standort 01",
    "active": true,
    "user_id": 2,
    "department_id": 2,
    "folder_id": null,
    "location_key": null,
    "sort_number": 2,
    "created_at": "2019-01-15 12:00:00",
    "updated_at": "2019-01-15 12:00:00",
    "deleted_at": null
  },
  {
    "id": 3,
    "name": "Standort 02",
    "active": true,
    "user_id": 2,
    "department_id": 3,
    "folder_id": null,
    "location_key": null,
    "sort_number": 3,
    "created_at": "2019-01-15 13:00:00",
    "updated_at": "2019-01-15 13:00:00",
    "deleted_at": null
  }
]
```

## Show

Show a single `Role` by `id`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/roles/{id}`

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/roles/2', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 2,
  "name": "Standort 01",
  "active": true,
  "user_id": 2,
  "department_id": 2,
  "folder_id": null,
  "location_key": null,
  "sort_number": 2,
  "created_at": "2019-01-15 12:00:00",
  "updated_at": "2019-01-15 12:00:00",
  "deleted_at": null
}
```

## Create

Create a new `Role`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/roles`

**Request Keys**

| Key                                     | Type    | Default            | Description                                                                                                                                                                                                         |
| --------------------------------------- | ------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `department_id` \*                      | integer | -                  | The ID of the [Department](https://docs.api.intratool.de/api-reference/departments) the `Role` is assigned to.                                                                                                      |
| `name` \*                               | string  | -                  | The name of the `Role.`                                                                                                                                                                                             |
| `active`                                | boolean | `true`             | Whether the `Role` is active.                                                                                                                                                                                       |
| `permissions_ids` \*                    | array   | -                  | The IDs of [Permissions](https://docs.api.intratool.de/api-reference/permissions) to grant the `Role`.                                                                                                              |
| `department_ids`                        | array   | Related Department | The IDs of [Departments](https://docs.api.intratool.de/api-reference/departments) the `Role` has "advanced access" to view content from.                                                                            |
| `infoboard_department_ids`              | array   | Related Department | The IDs of [Departments](https://docs.api.intratool.de/api-reference/departments) the `Role` is allowed to assign [InfoboardPosts](https://docs.api.intratool.de/api-reference/infoboard/infoboard-posts) to.       |
| `quick_task_assignments_department_ids` | array   | Related Department | The IDs of [Departments](https://docs.api.intratool.de/api-reference/departments) the `Role` is allowed to assign quick [TaskAssignments](https://docs.api.intratool.de/api-reference/tasks-2/task-assignments) to. |
| `folder_id`                             | integer | -                  | The ID of [Folder](https://docs.api.intratool.de/api-reference/folders) the `Role` is assigned to.                                                                                                                  |
| `location_key`                          | string  | -                  | The location description of the `Role`.                                                                                                                                                                             |
| `sort_number`                           | integer | Current highest +1 | The index of the `Role` related to the [Folder](https://docs.api.intratool.de/api-reference/folders).                                                                                                               |

Keys with `*` are required.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/roles', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'department_id' => 4,
        'name' => 'Standort 03',
        'permission_ids' => [1]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 4,
    "name": "Standort 03",
    "active": true,
    "user_id": 2,
    "department_id": 4,
    "folder_id": null,
    "location_key": null,
    "sort_number": 4,
    "created_at": "2019-01-15 14:00:00",
    "updated_at": "2019-01-15 14:00:00",
    "deleted_at": null
  }
}
```

## Update

Update an existing `Role` by `id`.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/roles/{id}`

**Request Keys**

| Key                        | Type    | Description                                                                                                                                                                                                   |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `department_id`            | integer | The ID of the [Department](https://docs.api.intratool.de/api-reference/departments) the `Role` is assigned to.                                                                                                |
| `name`                     | string  | The name of the `Role.`                                                                                                                                                                                       |
| `active`                   | boolean | Whether the `Role` is active.                                                                                                                                                                                 |
| `permissions_ids`          | array   | The IDs of [Permissions](https://docs.api.intratool.de/api-reference/permissions) to grant the `Role`.                                                                                                        |
| `department_ids`           | array   | The IDs of [Departments](https://docs.api.intratool.de/api-reference/departments) the `Role` has "advanced access" to view content from.                                                                      |
| `infoboard_department_ids` | array   | The IDs of [Departments](https://docs.api.intratool.de/api-reference/departments) the `Role` is allowed to assign [InfoboardPosts](https://docs.api.intratool.de/api-reference/infoboard/infoboard-posts) to. |
| `folder_id`                | integer | The ID of [Folder](https://docs.api.intratool.de/api-reference/folders) the `Role` is assigned to.                                                                                                            |
| `location_key`             | string  | The location description of the `Role`.                                                                                                                                                                       |
| `sort_number`              | integer | The index of the `Role` related to the [Folder](https://docs.api.intratool.de/api-reference/folders).                                                                                                         |

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/roles/4', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'department_ids' => [2, 3],
        'location_key' => 'Standort-03'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 4,
    "name": "Standort 03",
    "active": true,
    "user_id": 2,
    "department_id": 4,
    "folder_id": null,
    "location_key": "Standort-03",
    "sort_number": 4,
    "created_at": "2019-01-15 14:00:00",
    "updated_at": "2019-01-15 14:30:00",
    "deleted_at": null
  }
}
```

## Delete

Delete an existing `Role` by `id`.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/roles/{id}`

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('DELETE', '/api/roles/4', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": null
}
```