> 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` connect users to a primary department, module permissions, extended department access, and optional additional attributes.

## Model Definition

**Alias**

`role`

**Relations**

| Key                               | Relation                                                                | Type            | Relation Field(s)                        |
| --------------------------------- | ----------------------------------------------------------------------- | --------------- | ---------------------------------------- |
| `department`                      | [Department](/api-reference/departments.md)                             | Belongs to      | `department_id`                          |
| `departments`                     | [Departments](/api-reference/departments.md)                            | Belongs to many | `department_role`                        |
| `infoboardDepartments`            | [Departments](/api-reference/departments.md)                            | Belongs to many | `infoboard_department_role`              |
| `quickTaskAssignmentsDepartments` | [Departments](/api-reference/departments.md)                            | Belongs to many | `quick_task_assignments_department_role` |
| `permissions`                     | [Permissions](/api-reference/permissions.md)                            | Belongs to many | `permission_role`                        |
| `users`                           | [Users](/api-reference/users.md)                                        | Has many        | `role_id`                                |
| `folder`                          | [Folder](/api-reference/folders.md)                                     | Belongs to      | `folder_id`                              |
| `attributeSets`                   | [AttributeSets](/api-reference/additional-attributes/attribute-sets.md) | Morph to many   | Target entity type and ID                |

## List

List visible `Roles`.

**Definition**

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

**Request Keys**

| Key         | Type      | Default           | Description                          |
| ----------- | --------- | ----------------- | ------------------------------------ |
| `selects`   | `string`  | All fields        | Comma-separated fields to return.    |
| `relations` | `string`  | Default relations | Pipe-separated relations to include. |
| `limit`     | `integer` | No limit          | Maximum number of 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": 14,
    "name": "Engineering member",
    "active": true,
    "user_id": 7,
    "department_id": 6,
    "folder_id": 12,
    "location_key": "berlin",
    "sort_number": 1
  },
  {
    "id": 15,
    "name": "Product lead",
    "active": false,
    "user_id": 8,
    "department_id": 9,
    "folder_id": null,
    "location_key": "remote",
    "sort_number": 2
  }
]
```

## Show

Show one visible `Role`.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `role`    | `integer` | Role ID.    |

**Request Keys**

| Key         | Type     | Default           | Description                          |
| ----------- | -------- | ----------------- | ------------------------------------ |
| `selects`   | `string` | All fields        | Comma-separated fields to return.    |
| `relations` | `string` | Default relations | Pipe-separated relations to include. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 14,
  "name": "Engineering member",
  "active": true,
  "user_id": 7,
  "department_id": 6,
  "folder_id": 12,
  "location_key": "berlin",
  "sort_number": 1
}
```

## Availability Information

Show availability information for `Roles`.

**Definition**

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

**Request Keys**

| Key              | Type                                | Default         | Description                                       |
| ---------------- | ----------------------------------- | --------------- | ------------------------------------------------- |
| `department_ids` | `array or comma-separated integers` | All departments | Departments for which availability is calculated. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "available_per_department": 5,
  "departments": [
    {
      "department_id": 6,
      "available": 3,
      "used": 2
    },
    {
      "department_id": 9,
      "available": 4,
      "used": 1
    }
  ]
}
```

## Create

Create a new `Role`.

**Definition**

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

**Request Keys**

| Key                                     | Type                | Default            | Description                                                                        |
| --------------------------------------- | ------------------- | ------------------ | ---------------------------------------------------------------------------------- |
| `name`\*                                | `string`            | -                  | Unique role name.                                                                  |
| `department_id`\*                       | `integer`           | -                  | Primary [Department](/api-reference/departments.md) ID.                            |
| `active`                                | `boolean`           | `true`             | Whether users may use the role.                                                    |
| `folder_id`                             | `integer` \| `null` | `null`             | Parent [Folder](/api-reference/folders.md) ID.                                     |
| `location_key`                          | `string` \| `null`  | `null`             | Optional location identifier.                                                      |
| `sort_number`                           | `integer`           | Auto               | Order within the folder.                                                           |
| `permission_ids`                        | `array`             | No permissions     | [Permission](/api-reference/permissions.md) IDs granted through the role.          |
| `department_ids`                        | `array`             | Primary department | Departments whose content the role may access.                                     |
| `infoboard_department_ids`              | `array`             | Primary department | Departments available for Infoboard targeting.                                     |
| `quick_task_assignments_department_ids` | `array`             | Primary department | Departments available for quick task assignments.                                  |
| `attribute_set_ids`                     | `array`             | Current or no sets | [AttributeSets](/api-reference/additional-attributes/attribute-sets.md) to attach. |
| Additional attribute keys               | `mixed`             | Defined by set     | Values for attached AttributeFields.                                               |

Keys with `*` are required for creation.

**Behavior**

The authenticated user becomes `user_id`. The example supplies every relationship collection and additional-attribute value used to configure the new role.

**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' => [
        'name' => 'Customer Success lead',
        'department_id' => 6,
        'active' => true,
        'folder_id' => 12,
        'location_key' => 'berlin',
        'sort_number' => 3,
        'permission_ids' => [18, 24],
        'department_ids' => [6, 9],
        'infoboard_department_ids' => [6, 9],
        'quick_task_assignments_department_ids' => [6],
        'attribute_set_ids' => [[
            'id' => 32,
            'sort_number' => 1
        ]],
        'approval-limit' => 25000
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 16,
    "name": "Customer Success lead",
    "active": true,
    "user_id": 7,
    "department_id": 6,
    "folder_id": 12,
    "location_key": "berlin",
    "sort_number": 3
  }
}
```

## Update

Update an existing `Role`.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `role`    | `integer` | Role ID.    |

**Request Keys**

| Key                                     | Type                | Default            | Description                                                                        |
| --------------------------------------- | ------------------- | ------------------ | ---------------------------------------------------------------------------------- |
| `name`\*                                | `string`            | -                  | Unique role name.                                                                  |
| `department_id`\*                       | `integer`           | -                  | Primary [Department](/api-reference/departments.md) ID.                            |
| `active`                                | `boolean`           | `true`             | Whether users may use the role.                                                    |
| `folder_id`                             | `integer` \| `null` | `null`             | Parent [Folder](/api-reference/folders.md) ID.                                     |
| `location_key`                          | `string` \| `null`  | `null`             | Optional location identifier.                                                      |
| `sort_number`                           | `integer`           | Auto               | Order within the folder.                                                           |
| `permission_ids`                        | `array`             | No permissions     | [Permission](/api-reference/permissions.md) IDs granted through the role.          |
| `department_ids`                        | `array`             | Primary department | Departments whose content the role may access.                                     |
| `infoboard_department_ids`              | `array`             | Primary department | Departments available for Infoboard targeting.                                     |
| `quick_task_assignments_department_ids` | `array`             | Primary department | Departments available for quick task assignments.                                  |
| `attribute_set_ids`                     | `array`             | Current or no sets | [AttributeSets](/api-reference/additional-attributes/attribute-sets.md) to attach. |
| Additional attribute keys               | `mixed`             | Defined by set     | Values for attached AttributeFields.                                               |

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/roles/16', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'name' => 'Customer Experience lead',
        'active' => true,
        'department_id' => 9,
        'permission_ids' => [18, 24, 27],
        'department_ids' => [6, 9],
        'infoboard_department_ids' => [9],
        'quick_task_assignments_department_ids' => [6, 9],
        'attribute_set_ids' => [[
            'id' => 32,
            'sort_number' => 1
        ]],
        'approval-limit' => 30000
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 16,
    "name": "Customer Experience lead",
    "active": true,
    "user_id": 7,
    "department_id": 9,
    "folder_id": 12,
    "location_key": "berlin",
    "sort_number": 3
  }
}
```

## Delete

Delete an existing `Role`.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `role`    | `integer` | Role ID.    |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

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