Selective Data Sharing

The owner of an IOTICSpace is in control of all its twins, and therefore of all the data stored and streaming through them. Owners can decide to make their twins visible (or not) and to share data with all, none, or a select number of parties and, by extension, join one or more data ecosystems or consortia.

This page will cover:


An introduction to Selective Data Sharing

IOTICS distinguishes between two settings:

  1. Visibility (the F in FAIR)
    • whether a Digital Twin's metadata is visible (or not) to another IOTICSpace
    • this is set by updating the Host Twin's or Digital Twin's Visibility property
  2. Accessibility (the A in FAIR)
    • whether a Digital twin's data can be accessed (or not) by a Digital Twin from another IOTICSpace
    • it can be enabled for the entire IOTICSpace and selectively on a twin-by-twin basis
    • this is set by updating the Host Twin's or Digital Twin's AllowList property

Visibility (the F in FAIR)

The Visibility property determines whether a Digital Twin can be found by searching for its metadata. Two settings exist: PRIVATE and PUBLIC.

VisibilitySearch from your own IOTICSpaceSearch from another IOTICSpace
PRIVATE✔️
The twin can be found and described

The twin cannot be found and therefore cannot be described
PUBLIC✔️
The twin can be found and described
✔️
The twin can be found and described

🚧

Default settings: Host Twin = PUBLIC, Digital Twin = PRIVATE


How to set a Digital Twin's visibility (PUBLIC, PRIVATE)

curl --request PATCH \
     --url https://example.iotics.space/qapi/twins/did%3Aiotics%3Adidexample1234abcd \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Iotics-ClientAppId: ExampleAppID' \
     --data '
{
     "newVisibility": {
          "visibility": "PUBLIC"
     },
}
'
import requests

url = "https://example.iotics.space/qapi/twins/did%3Aiotics%3Adidexample1234abcd"

payload = {
    "newVisibility": {"visibility": "PUBLIC"}
}
headers = {
    "Accept": "application/json",
    "Iotics-ClientAppId": "ExampleAppID",
    "Content-Type": "application/json"
}

response = requests.request("PATCH", url, json=payload, headers=headers)

print(response.text)
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"newVisibility\":{\"visibility\":\"PUBLIC\"}");
Request request = new Request.Builder()
  .url("https://example.iotics.space/qapi/twins/did%3Aiotics%3Adidexample1234abcd")
  .patch(body)
  .addHeader("Accept", "application/json")
  .addHeader("Iotics-ClientAppId", "ExampleAppID")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

Accessibility (the A in FAIR)

Access permissions can be enabled:

  • for the entire IOTICSpace, setting the Host Twin's AllowList
  • on a twin-by-twin basis, setting a Digital Twin's individual AllowList

The Host Twin controls access to the entire IOTICSpace and therefore restricts or enables access to all the Digital Twins within the IOTICSpace to all, none or a select group of other IOTICSpaces. Granular access control can be achieved by setting an individual Digital Twin's access permissions.


Selective data sharing for the entire IOTICSpace

This is enabled or restricted by updating the Host Twin's AllowList property.

Available access levels of the AllowList are:

  • ALLOW ALL - allows access from any other IOTICSpace
  • ALLOW SOME - allows access from specific IOTICSpaces only
  • ALLOW NONE - denies access to any other IOTICSpace

🚧

The Host Twin's default setting is ALLOW ALL


Selective data sharing for a specific Digital Twin

This is enabled or restricted by updating the Digital Twin's AllowList property.

Available access levels of the AllowList are:

  • ALLOW ALL - allows access to the twin from any other IOTICSpace (provided the Host Twin allows this IOTICSpace)
  • ALLOW SOME - allows access from specific IOTICSpaces only (provided the Host Twin allows this specific IOTICSpace)
  • ALLOW NONE - denies access to any other IOTICSpace (irrespective of the Host Twin's AllowList setting)

🚧

A Digital Twin's default setting is ALLOW NONE


Designing for granular access control

Combining access permissions for the entire IOTICSpace with individual twins results in granular access control.

When configuring your access permissions, consider the following best practices:

  1. What is the least restrictive data access you need? Consider that:
    • Restricting the Host Twin to ALLOW NONE may be tempting initially, however will leave you with an IOTICSpace unable to interact with anyone (therefore unable to join any data ecosystem). We recommend the Host Twin is set to ALLOW SOME or ALLOW ALL for future extensibility.
    • Updating the AllowList of individual Digital Twins can be done by any user, the Host Twin can only be updated by admins.
  2. Do you need to share all or only parts of a Digital Twin's data? If you only need to share some of your Digital Twin's metadata and data with a third party, consider that:
    • in IOTICS the entire Digital Twin will be shared. If you still want to share only some of it, you can clone your existing twin, remove any details you don't want to share, and share that new twin instead.
    • this will also allow you to keep on top of your access permissions later, once you may need to manage more than two third parties with different data access needs (search by Host Twin DID will be handy).
  3. Is there any potential conflict between your Host Twin and Digital Twin settings? Consider to:
    • regularly review your access needs. If the access permissions contradict themselves, the most restrictive and secure permissions are applied. This means that both the Host Twin and the Digital Twin need to allow access if this is desired. If the Host Twin restricts access, but the Digital Twin itself doesn't, access isn't given. Similarly, if the Host Twins allows access but the Digital Twin doesn't, access isn't given either.
    • if you need help designing your access permissions please do get in touch with us.

The following table details all possible combinations

HOST TWINDIGITAL TWINAccess from your own IOTICSpaceAccess from another IOTICSpace
ALLOW NONEALLOW NONE✔️ The Digital Twin can be accessed (followed)❌ The Digital Twin cannot be accessed (followed)
ALLOW SOME✔️ The Digital Twin can be accessed (followed)❌ The Digital Twin cannot be accessed (followed)
ALLOW ALL✔️ The Digital Twin can be accessed (followed)❌ The Digital Twin cannot be accessed (followed)
ALLOW SOMEALLOW NONE✔️ The Digital Twin can be accessed (followed)❌ The Digital Twin cannot be accessed (followed)
ALLOW SOME✔️ The Digital Twin can be accessed (followed)✔️ The Digital Twin can ONLY be accessed (followed) by IOTICSpaces that are allowed in both the Host Twin's and the Digital Twin's AllowList
ALLOW ALL✔️ The Digital Twin can be accessed (followed)✔️ The Digital Twin can ONLY be accessed (followed) by IOTICSpaces that are allowed in the Host Twin's AllowList
ALLOW ALLALLOW NONE✔️ The Digital Twin can be accessed (followed)❌ The Digital Twin cannot be accessed (followed)
ALLOW SOME✔️ The Digital Twin can be accessed (followed)✔️ The Digital Twin can ONLY be accessed (followed) by IOTICSpaces that are allowed in the Digital Twin's AllowList
ALLOW ALL✔️ The Digital Twin can be accessed (followed)✔️ The Digital Twin can be accessed (followed) by any IOTICSpace

🚧

Any conflicts between settings will resolve in the more secure and restrictive way

For example, if the Host Twin is set to ALLOW NONE and the Twin is set to ALLOW ALL, no other IOTICSpace can access any twin.


How to set a Digital Twin's access permissions (ALLOW ALL, ALLOW SOME, ALLOW NONE)

Updating the Host Twin or an individual Digital Twin follows the same principle, meaning that the AllowList has to be updated to either ALLOW ALL, NONE or ALLOW SOME.

When updating access permissions you need to remove existing allow to avoid a clash of permissions. This is done by deleting the hostAllowList property.

AllowListURI value
ALLOW ALLhttp://data.iotics.com/public#allHosts
ALLOW SOMEDesired DID or list of DIDs that should be authorised.
For example:
did:iotics:otherdidexample1234abcd
ALLOW NONEhttp://data.iotics.com/public#noHost

🚧

Check you have permissions to update the Host Twin and/or Digital Twin

Follow this step-by-step guide if you need help updating the Host Twin.

ALLOW ALL
AGENT_TOKEN='example_Agent_TokenABCdefghijklmnopqrstuvwxyz1234567890'
A_TWIN_DID='did%3Aiotics%3Adidexample1234abcd'
curl -X PATCH "http://localhost:8081/qapi/twins/$A_TWIN_DID" \
 -H "accept: application/json" \
 -H "Iotics-ClientAppId: app1" \
 -H "Authorization: Bearer $AGENT_TOKEN" \
 -H "Content-Type: application/json"\
  -d "{\"properties\":{\"added\":[{\"key\":\"http://data.iotics.com/public#hostAllowList\",\"uriValue\":{\"value\":\"http://data.iotics.com/public#allHosts\"}}],\"deletedByKey\":[\"http://data.iotics.com/public#hostAllowList\"]}}"
allow_all_property = ModelProperty(key='http://data.iotics.com/public#hostAllowList',
                                    uri_value=Uri(value='http://data.iotics.com/public#allHosts'))
api.update_twin(twin_id=,did:iotics:didexample1234abcd,
                add_props=[
                    allow_all_property
                ],
                del_props_by_key=[
                    'http://data.iotics.com/public#hostAllowList'
                ])
ALLOW SOME
AGENT_TOKEN='example_Agent_TokenABCdefghijklmnopqrstuvwxyz1234567890'
A_TWIN_DID='did%3Aiotics%3Adidexample1234abcd'
OTHER_HOST_TWIN_DID='did:iotics:otherdidexample1234abcd'
curl -X PATCH "http://localhost:8081/qapi/twins/$A_TWIN_DID" \
 -H "accept: application/json" \
 -H "Iotics-ClientAppId: app1" \
 -H "Authorization: Bearer $AGENT_TOKEN" \
 -H "Content-Type: application/json"\
  -d "{\"properties\":{\"added\":[{\"key\":\"http://data.iotics.com/public#hostAllowList\",\"uriValue\":{\"value\":\"$OTHER_HOST_TWIN_DID\"}}],\"deletedByKey\":[\"http://data.iotics.com/public#hostAllowList\"]}}"
allow_other_host_property = ModelProperty(key='http://data.iotics.com/public#hostAllowList',
                                    uri_value=Uri(value=did:iotics:otherdidexample1234abcd))
api.update_twin(twin_id=did:iotics:didexample1234abcd,
                add_props=[
                    allow_other_host_property
                ],
                del_props_by_key=[
                    'http://data.iotics.com/public#hostAllowList'
                ])
ALLOW NONE
AGENT_TOKEN='example_Agent_TokenABCdefghijklmnopqrstuvwxyz1234567890'
A_TWIN_DID='did%3Aiotics%3Adidexample1234abcd'
curl -X PATCH "http://localhost:8081/qapi/twins/$A_TWIN_DID" \
 -H "accept: application/json" \
 -H "Iotics-ClientAppId: app1" \
 -H "Authorization: Bearer $AGENT_TOKEN" \
 -H "Content-Type: application/json"\
  -d "{\"properties\":{\"added\":[{\"key\":\"http://data.iotics.com/public#hostAllowList\",\"uriValue\":{\"value\":\"http://data.iotics.com/public#noHost\"}}],\"deletedByKey\":[\"http://data.iotics.com/public#hostAllowList\"]}}"
allow_none_property = ModelProperty(key='http://data.iotics.com/public#hostAllowList',
                                    uri_value=Uri(value='http://data.iotics.com/public#noHost'))
api.update_twin(twin_id=did:iotics:didexample1234abcd,
                add_props=[
                    allow_none_property
                ],
                del_props_by_key=[
                    'http://data.iotics.com/public#hostAllowList'
                ])