# 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](/api-reference/departments.md) so that every member of a [Department](/api-reference/departments.md) has the same `Permissions`.

## Model Definition

### Alias

`role`

### Relations

| Key                               | Relation                                                                | Type            | Relation Field(s)                                                                                                                                |
| --------------------------------- | ----------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `user`                            | [User](/api-reference/users.md)                                         | Belongs to      | `user_id`                                                                                                                                        |
| `department`                      | [Department](/api-reference/departments.md)                             | Belongs to      | `department_id`                                                                                                                                  |
| `folder`                          | [Folder](/api-reference/folders.md)                                     | Belongs to      | `folder_id`                                                                                                                                      |
| `departments`                     | [Departments](/api-reference/departments.md)                            | Belongs to many | Intermediate table                                                                                                                               |
| `infoboardDepartments`            | [Departments](/api-reference/departments.md)                            | Belongs to many | Intermediate table                                                                                                                               |
| `quickTaskAssignmentsDepartments` | [Departments](/api-reference/departments.md)                            | Belongs to many | Intermediate table                                                                                                                               |
| `permissions`                     | [Permissions](/api-reference/permissions.md)                            | Belongs to many | Intermediate table                                                                                                                               |
| `users`                           | [Users](/api-reference/users.md)                                        | Has many        | `users.role_id`                                                                                                                                  |
| `attributeSets`                   | [AttributeSets](/api-reference/additional-attributes/attribute-sets.md) | Morph to many   | `target_entity_attribute_set.target_entity_type`, `target_entity_attribute_set.target_entity_id`, `target_entity_attribute_set.attribute_set_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](/api-reference/departments.md) 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](/api-reference/permissions.md) to grant the `Role`.                                                                                                                                                                |
| `department_ids`                        | array   | Related Department | The IDs of [Departments](/api-reference/departments.md) the `Role` has "advanced access" to view content from.                                                                                                                              |
| `infoboard_department_ids`              | array   | Related Department | The IDs of [Departments](/api-reference/departments.md) the `Role` is allowed to assign [InfoboardPosts](/api-reference/infoboard/infoboard-posts.md) to.                                                                                   |
| `quick_task_assignments_department_ids` | array   | Related Department | The IDs of [Departments](/api-reference/departments.md) the `Role` is allowed to assign quick [TaskAssignments](/api-reference/tasks-2/task-assignments.md) to.                                                                             |
| `attribute_set_ids`                     | array   | -                  | Attribute sets to link to this role (IDs or objects with `id` and optional `sort_number`, see [Linking AttributeSets to target entities](/api-reference/additional-attributes/attribute-sets.md#linking-attributesets-to-target-entities)). |
| `folder_id`                             | integer | -                  | The ID of [Folder](/api-reference/folders.md) 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](/api-reference/folders.md).                                                                                                                                                                 |

Keys with `*` are required.

#### Advanced Key-Specifications

* `attribute_set_ids` - Supports two formats (see [Linking AttributeSets to target entities](/api-reference/additional-attributes/attribute-sets.md#linking-attributesets-to-target-entities)):
  * `[1, 2, 3]`
  * `[{"id": 1, "sort_number": 1}, {"id": 2, "sort_number": 2}]`

**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](/api-reference/departments.md) 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](/api-reference/permissions.md) to grant the `Role`.                                                                                                                                                                |
| `department_ids`           | array   | The IDs of [Departments](/api-reference/departments.md) the `Role` has "advanced access" to view content from.                                                                                                                              |
| `infoboard_department_ids` | array   | The IDs of [Departments](/api-reference/departments.md) the `Role` is allowed to assign [InfoboardPosts](/api-reference/infoboard/infoboard-posts.md) to.                                                                                   |
| `attribute_set_ids`        | array   | Attribute sets to link to this role (IDs or objects with `id` and optional `sort_number`, see [Linking AttributeSets to target entities](/api-reference/additional-attributes/attribute-sets.md#linking-attributesets-to-target-entities)). |
| `folder_id`                | integer | The ID of [Folder](/api-reference/folders.md) 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](/api-reference/folders.md).                                                                                                                                                                 |

#### Advanced Key-Specifications

* `attribute_set_ids` - Supports two formats (see [Linking AttributeSets to target entities](/api-reference/additional-attributes/attribute-sets.md#linking-attributesets-to-target-entities)):
  * `[1, 2, 3]`
  * `[{"id": 1, "sort_number": 1}, {"id": 2, "sort_number": 2}]`

**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
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.api.intratool.de/api-reference/roles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.