Policies resources

An IoT developer can create, read, update and delete a Policy via the version 2 of the HTTP API.

Policies resource

By default a policy is related to a thing or another entity. However, policies have their own lifecycle:

While creating a thing without explicit policy assignment, a default policy is created. Thus, the creator will aquire all permissions to fully control the thing and the policy. In such a case the Policy ID equals the Thing ID.
Deleting a policy does not implicitly delete other entities (e.g. Things) which use the policy.

Example

Given you need to support the following scenario:

Owner: The thing my.namespace:thing-0123 is owned by a user. Thus, he needs full access and admin rights for the complete thing.
In our example his ID is 8c36bc60-xxxx-xxxx-xxxx-4ed6ce7ed64c
Observer of changes at featureX and featureY:
- Another application needs to be informed on each change at those features. In our example its ID is eebbb40e-xxxx-xxxx-xxxx-f79a4653946b:observer-client.
- There is a group of users who are allowed to read both features. In our example the group ID is 93f24210-xxxx-xxxx-xxxx-620a03644e93
Privacy The value of the “city” property at “featureY” is confidential and needs to be “hidden” from the group of users.

policy example

tip Find the complete policy in JSON notation at Policy - example

Note on policy ID and labels

Each policy ID needs to follow the pattern <namespace>:<policy-name>.

note Due to the fact that a policy ID or label might need to be set in the path, we have restricted the set of allowed characters to those for Uniform Resource Identifiers (URI) see http://www.ietf.org/rfc/rfc2396.txt.

Note on conditional requests

The Policies resources support Conditional Requests. Details are described in the Ditto HTTP API concepts.

Tip on subject placeholder

tip While creating a policy via the HTTP API, it might be cumbersome to find out your own technical ID, which is crucial to add to the policy, in order to still have permission to edit it at a later point in time. For such a case you can use the placeholder {{ request:subjectId }}. Once the request was processed at the Things service it will be replaced with the ID of the requesting user.

For creating permissions for connected devices (e.g. via Bosch IoT Hub), you can use the placeholder {{ request:solutionId }},
e.g. integration:{{ request:solutionId }}:hub.

Tip on how to derive the subject from your JWT

You can find the subject IDs for your current authentication, using the Who Am I-REST call. Find the resource in the API docs, at the end of the Policies section