Each connected Entity has at least one owner, usually the or who onboarded it. Owners can share access to their Entities by assigning permissions to others.

Permissions can be assigned to Principals, which represent individual Users and Clients, or groups of them as Collectives and Tenants. Each Principal is uniquely identified by a .

​
Types of permissions

Each Entity supports four types of permissions that can be assigned to a Principal:

  • 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.

​
Permission inheritance

Individual Users and Clients may automatically inherit Viewer and Contributor permissions on an Entity when they are an administrator of its Tenant or part of a shared Collective.

​
What you’ll need

  • Your API credentials
  • An Entity of any type that you own
  • The ID of a User, Client, Tenant or Collective

​
Let’s try it out

1

Understand who can access your Entity (optional)

You may want to List all permissions for an Entity, to understand who can access it.

To do so, you must specify the of an Entity you own.

Response (Body)
{
  "data": [
    {
      "entityId": "3c90c3cc-[...]-8dd25736052a",
      "principalId": "b8a4d7e5-[...]-572a00302df9",
      "permissionLevels": [
        "Viewer"
      ],
    }
  ], ...
}

You’ll find an array of for each you’ve shared access with.

2

Share access with someone else

To share access with someone else, Add permissions for them on your Entity.

Specify the of an Entity you own, and set the to that of the User, Client, Collective, or Tenant you’re sharing access with. Lastly, set the you are assigning to them.

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

Request (Example)
{
  "principalId": "b8a4d7e5-[...]-572a00302df9",
  "permissionLevel": "Administer"
}