> For the complete documentation index, see [llms.txt](https://docs.api.intratool.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.api.intratool.de/api-reference/roles.md). # 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** `GET` `/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** `GET` `/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** `POST` `/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** `PUT` `/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** `DELETE` `/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 } ```