> 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

## Introduction

`EntityPermissions` grant a resource-specific restriction key to a user, role, or department for one target resource. See the [Entity Permissions capability](/introduction/resource-capabilities/entity-permissions.md) for supported resources and [Restricted Scope](/introduction/entity-permissions/restricted-scope.md) for direct and inherited enforcement.

Entity aliases and IDs are polymorphic: both referenced records must exist and the target resource must support entity permissions.

## Model Definition

**Permission Keys**

* `administrate` - Grants administrative access where the target resource supports it.
* `administrationRights` - Grants Infoboard administration rights where supported.
* `comment` - Grants permission to comment where supported.
* `view` - Grants permission to view the target resource.
* `viewFormMessages` - Grants permission to view messages submitted through a Form.
* `write` - Grants permission to create content where supported.

**Permission Entity Types**

* `user` - Grants the permission to a [User](/api-reference/users.md).
* `role` - Grants the permission to a [Role](/api-reference/roles.md).
* `department` - Grants the permission to a [Department](/api-reference/departments.md).

**Attributes**

| Key                    | Type      | Description                                                                       |
| ---------------------- | --------- | --------------------------------------------------------------------------------- |
| `key`                  | `string`  | Selects one of the supported [Permission Keys](#permission-keys).                 |
| `permission_entity`    | `string`  | Selects one of the supported [Permission Entity Types](#permission-entity-types). |
| `permission_entity_id` | `integer` | ID of that permission entity.                                                     |
| `target_entity`        | `string`  | Alias of the restricted target resource.                                          |
| `target_entity_id`     | `integer` | ID of that target resource.                                                       |

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

List `EntityPermissions` for one target entity.

**Definition**

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

**Route Parameters**

| Parameter                      | Type                  | Description                                 |
| ------------------------------ | --------------------- | ------------------------------------------- |
| `entityPermissionTargetEntity` | `string/integer path` | Contains `{targetEntity}/{targetEntityId}`. |

**Request Keys**

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

**Behavior**

The catch-all route binding resolves exactly two path segments. The example lists all grants for Form 10.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 51,
    "key": "view",
    "permission_entity": "department",
    "permission_entity_id": 6,
    "target_entity": "form",
    "target_entity_id": 10,
    "created_at": "2026-08-06 09:00:00",
    "updated_at": "2026-08-06 09:00:00",
    "deleted_at": null
  },
  {
    "id": 52,
    "key": "write",
    "permission_entity": "user",
    "permission_entity_id": 7,
    "target_entity": "form",
    "target_entity_id": 10,
    "created_at": "2026-08-06 09:05:00",
    "updated_at": "2026-08-06 09:05:00",
    "deleted_at": null
  }
]
```

## Show

Show one `EntityPermission`.

**Definition**

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

**Route Parameters**

| Parameter          | Type      | Description          |
| ------------------ | --------- | -------------------- |
| `entityPermission` | `integer` | EntityPermission 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/entity-permissions/51', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 51,
  "key": "view",
  "permission_entity": "department",
  "permission_entity_id": 6,
  "target_entity": "form",
  "target_entity_id": 10,
  "created_at": "2026-08-06 09:00:00",
  "updated_at": "2026-08-06 09:00:00",
  "deleted_at": null
}
```

## Create or Reuse

Create or reuse an `EntityPermission` for one target entity.

**Definition**

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

**Request Keys**

| Key                      | Type      | Default | Description                                               |
| ------------------------ | --------- | ------- | --------------------------------------------------------- |
| `key`                    | `string`  | `view`  | Supported restriction key.                                |
| `permission_entity`\*    | `string`  | -       | Alias of the permission entity.                           |
| `permission_entity_id`\* | `integer` | -       | Existing ID for that alias.                               |
| `target_entity`\*        | `string`  | -       | Alias of a target resource supporting entity permissions. |
| `target_entity_id`\*     | `integer` | -       | Existing ID for that target alias.                        |

Keys with `*` are required.

**Behavior**

The API returns the existing record when the complete key/entity/target combination already exists; otherwise it creates one. Every value needed for the response is present in the example request except generated IDs and timestamps.

**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' => 'write',
        'permission_entity' => 'user',
        'permission_entity_id' => 19,
        'target_entity' => 'form',
        'target_entity_id' => 10
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 53,
    "key": "write",
    "permission_entity": "user",
    "permission_entity_id": 19,
    "target_entity": "form",
    "target_entity_id": 10,
    "created_at": "2026-08-06 10:00:00",
    "updated_at": "2026-08-06 10:00:00",
    "deleted_at": null
  }
}
```

## Delete

Delete an existing `EntityPermission`.

**Definition**

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

**Route Parameters**

| Parameter          | Type      | Description          |
| ------------------ | --------- | -------------------- |
| `entityPermission` | `integer` | EntityPermission 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/53', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

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