> ## Documentation Index
> Fetch the complete documentation index at: https://docs.der-connect.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Sharing access

> Learn how to share Entities with other Applications.

Each connected Entity has at least one owner, usually the <Tooltip tip="An application, authenticated with client ID and secret">Application</Tooltip> who onboarded it. Owners can share access to their Entities by assigning permissions directly to other Applications or to a Collective of them.

Permissions can be assigned to any Application, uniquely identified by an <Tooltip tip="A unique ID of the Application">applicationId</Tooltip>.

## Collectives

Permissions can also be assigned to a Collective of Applications, identified by a <Tooltip tip="A unique ID of the Collective">collectiveId</Tooltip>.

Applications automatically inherit all permissions assigned to a Collective when they are or become a member of it.

## Types of permissions

Each Entity supports four types of permissions that can be assigned to an Application:

* **Viewer** – Can access Readings, settings, and previously triggered Commands.
* **Contributor** – Can trigger Commands.
* **Administer** – Can manage certain settings.
* **Owner** – Can manage permissions and all settings.

## What you’ll need

* A valid access (bearer) token
* An Entity of any type that your Application owns
* The ID of a Collective or another Application (<Tooltip tip="The unique ID of the Application or Collective">principalId</Tooltip>)

## Let's try it out

<Note>
  Our endpoints refer to a `principalId` as a common name for both Application and Collectives IDs. We currently updating the naming of these properties.
</Note>

<Steps>
  <Step title="Understand who can access your Entity (optional)">
    You may want to [List all permissions for an Entity](/api-reference/endpoint/core-resources/entity-permissions/list-permissions-by-entity), to understand who can access it.

    To do so, you must specify the <Tooltip tip="The ID of the Entity">entityId</Tooltip> of an Entity you own.

    ```json Response (Body) {5, 7} theme={null}
    {
      "data": [
        {
          "entityId": "3c90c3cc-[...]-8dd25736052a",
          "principalId": "b8a4d7e5-[...]-572a00302df9",
          "permissionLevels": [
            "Viewer"
          ],
        }
      ], ...
    }
    ```

    You'll find an array of <Tooltip tip="Available options: Viewer, Contributer, Administer, Owner">permissionLevels</Tooltip> for each <Tooltip tip="The unique ID of a User, Client, Collective, or Tenant.">principalId</Tooltip> you've shared access with.
  </Step>

  <Step title="Share access with someone else">
    To share access with someone else, [Add permissions for them on your Entity](/api-reference/endpoint/core-resources/entity-permissions/add-permissions-to-an-entity).

    Specify the <Tooltip tip="The ID of the Entity">entityId</Tooltip> of an Entity you own, and set the <Tooltip tip="The unique ID of the Application or Collective">principalId</Tooltip> to the Application you're sharing access with. Lastly, set the <Tooltip tip="Available options: Viewer, Contributer, Administer, Owner">permissionLevel</Tooltip> you are assigning to them.

    You may need to make multiple requests to assign multiple permission levels.

    ```json Request (Example) theme={null}
    {
      "principalId": "b8a4d7e5-[...]-572a00302df9",
      "permissionLevel": "Administer"
    }
    ```
  </Step>
</Steps>