> 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/entity-permissions.md).

# EntityPermissions

`EntityPermissions` are a layer of permissions directly applied on user generated contents and are one core part of the intratool permission handling.

To read more about the concept of `EntityPermissions`, head to the [introduction section about them](/introduction/entity-permissions.md).

## Model Definition

### Structure

| Field                  | Description                                                   | Example Value          |
| ---------------------- | ------------------------------------------------------------- | ---------------------- |
| `key`                  | The permission key.                                           | `view`                 |
| `permission_entity`    | Model (alias) to grant the permission key for.                | `user` or `department` |
| `permission_entity_id` | The `id` of the Model to grant the permission key for.        | `25`                   |
| `target_entity`        | Target Model (alias) to grant the permission key for.         | `taskAssignment`       |
| `target_entity_id`     | The `id` of the target Model to grant the permission key for. | `10`                   |

### Relations

| Key                | Relation          | Type     | Relation Field(s)                         |
| ------------------ | ----------------- | -------- | ----------------------------------------- |
| `permissionEntity` | Permission Entity | Morph to | `permission_entity, permission_entity_id` |
| `targetEntity`     | Target Entity     | Morph to | `target_entity, target_entity_id`         |

## List by target entity

Get a list of `EntityPermissions` for given target entity.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/entity-permissions/{targetEntity}/{targetEntityId}`

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response Body**

```json
[
  {
    "id": 1,
    "key": "view",
    "permission_entity": "department",
    "permission_entity_id": 25,
    "target_entity": "taskAssignment",
    "target_entity_id": 10,
    "created_at": "2024-06-01 12:00:00",
    "updated_at": "2024-06-01 12:00:00",
    "deleted_at": null
  },
  {
    "id": 2,
    "key": "view",
    "permission_entity": "department",
    "permission_entity_id": 26,
    "target_entity": "taskAssignment",
    "target_entity_id": 10,
    "created_at": "2024-06-01 13:00:00",
    "updated_at": "2024-06-01 13:00:00",
    "deleted_at": null
  }
]
```

## Show

Show a single `EntityPermission` by `id`.

**Definition**

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

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 1,
  "key": "view",
  "permission_entity": "department",
  "permission_entity_id": 25,
  "target_entity": "taskAssignment",
  "target_entity_id": 10,
  "created_at": "2024-06-01 12:00:00",
  "updated_at": "2024-06-01 12:00:00",
  "deleted_at": null
}
```

## Create or update

Create a new `EntityPermission`. When a `EntityPermission` with the given data already exits, the `updated_at` timestamp will be updated.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/entity-permissions`

**Request Keys**

| Key                      | Type    | Default | Description                                                   |
| ------------------------ | ------- | ------- | ------------------------------------------------------------- |
| `key`\*                  | string  | -       | The permission key.                                           |
| `permission_entity`\*    | string  | -       | Model (alias) to grant the permission key for.                |
| `permission_entity_id`\* | integer | -       | The `id` of the Model to grant the permission key for.        |
| `target_entity`\*        | string  | -       | Target Model (alias) to grant the permission key for.         |
| `target_entity_id`\*     | integer | -       | The `id` of the target Model to grant the permission key for. |

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/entity-permissions', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'key' => 'view',
        'permission_entity' => 'department',
        'permission_entity' => 27,
        'target_entity' => 'taskAssignment',
        'permission_entity' => 10,
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response Body**

```json
{
  "status": "success",
  "data": {
    "id": 3,
    "key": "view",
    "permission_entity": "department",
    "permission_entity_id": 27,
    "target_entity": "taskAssignment",
    "target_entity_id": 10,
    "created_at": "2024-06-01 14:00:00",
    "updated_at": "2024-06-01 14:00:00",
    "deleted_at": null
  }
}
```

## Delete

Delete an existing `EntityPermission` by `id`.

**Definition**

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

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": []
}
```