# Rules (Twin visibility)
# About this guide
This guide describes how to use the "twin" rule in role to control access to Twins. It is divided into the following sections:
| Section | Contents |
|---|---|
| Rules | Introduction to rules on the Trusted Twin platform. |
| Preparation | In this section we create an account, a role, a user and a few Twins. |
| Scenarios | Example scenarios illustrating the use of the "twin" rule. |
| Resources | Further resources related to this guide. |
In this guide we use cURL to provide examples. For more information about cURL, please see our cURL quickstart guide.
# Rules
A rule on the Trusted Twin platform is used to manage visibility and access of a user to a resource or to define conditions triggering a notification event. Rules follow the Rule Engine Syntax(opens new window).
Rules are used in roles, Identities, and Ledger Entries. Rules in a role control the access of a user to Twins, Identities and Ledger Entries. They are held in the "rules" attribute of a role.
In this guide, we are going to focus on the "twin" rule in a role.
# Visibility
The visibility of data on the Trusted Twin platform can be managed from two perspectives:
- Resource perspective: the visibility of an Identity or a Ledger Entry.
- User perspective: Twin, Identity and Ledger Entry.
# Resource perspective
The resource perspective is designed to manage visibility in relation to users belonging to other Trusted Twin accounts. The resource visibility rules are used each time a user belonging to a different account tries to access a resource owned by another account.
Please note that the resource visibility rules do not apply to users accessing resources owned by their account. All resources owned by the account are visible to all of its users.
# User perspective
User perspective was designed to manage visibility of resources on the user level. Visibility rules defined in the user role control the access of the user to Twins (Twin rule), Identities (Identity rule) or Entries in a Ledger (Entry rule). Rules applied from the user perspective apply to all resources, including resources owned by the user’s own account.
Visibility rules are defined for each role you create (see create_user_role). They can be modified when updating a role (see update_user_role).
# Scenarios
We are going to go through various scenarios where a different visibility rules is required for a Ledger Entry:
| Scenario | Rule | Description |
|---|---|---|
| Scenario 1 | "twin": null | User with the role can get all Twins within the account they belong to. |
| Scenario 2 | "twin": "twin == 'b5d81fb3-9c66-4a19-8433-e763eec3f573'" | User with the role can access only the Twin with the given Twin UUID within the account hey belong to. |
| Scenario 3 | "visibility": "account in [{account},{account}]" | User with the role can only get a Twin with "department" value in the description field of the Twin equal to "department" value in the description field of the user. |
| Scenario 4 | "visibility": "account in [{account},{account}]" | User with the role can only create a Twin with "department" value in the description field of the Twin equal to "department" value in the description field of the user. |
# Preparation
# Account
For the purpose of this guide, we create a Trusted Twin account (account UUID 012623f3-1a18-487d-8dd2-9c26863a02f0). For more information about how to create an account, please see the Account creation section.
# Role
On this account (account UUID 012623f3-1a18-487d-8dd2-9c26863a02f0), we create a role (role UUID 6b7ee989-e02d-4cbc-9a2d-ab405bb1b9b7) with permissions to perform the "get_twin", "get_twin_ledger_entry", and "get_twin_identity" actions.
Please note that the "twin" rule in the "rules" section is currently set to its default value null. This means that there are no restrictions for the user with the role regarding the access to Twins. When it comes to Twins created in the account (account UUID 012623f3-1a18-487d-8dd2-9c26863a02f0), the user with this role will be able to see all Twins owned by this account.
# User
Next, we create a user with this role.
We create as well a User Secret (API key) for this user.
# Twins
# Scenario 1
| Rule | Description |
|---|---|
"twin": null | User with the role can access all Twins within the account they belong to. |
Let's check whether we can see the Twins with as the user with the role we created.
# Role
# Requests
In order to retrieve the Twins, we send requests to the get_twin endpoint to retrieve the respective Twins based on their Twin UUIDs.
# Responses
# Scenario 2
| Rule | Description |
|---|---|
"twin": "twin == 'b5d81fb3-9c66-4a19-8433-e763eec3f573'" | User with the role can access only the Twin with the given Twin UUID within the account hey belong to. |
# Role update
# Requests
In order to retrieve the Twins, we send a request to the get_twin endpoint.
# Response
# Scenario 3
| Rule | Description |
|---|---|
"twin": "TWIN.department == USER.department" | User with the role can only get a Twin with "department" value in the description field of the Twin equal to "department" value in the description field of the user. |
# Role and user
# Requests
In order to retrieve the Twins, we send requests to the get_twin endpoint.
# Response
# Scenario 4
| Rule | Description |
|---|---|
"twin": "TWIN.department == USER.department" | User with the role can only create a Twin with "department" value in the description field of the Twin equal to "department" value in the description field of the user. |
# Requests
In order to retrieve the Twins, we send a request to the create_twin endpoint.
# Response
The user can only create a Twin if a description field contains "department": "sales". The user cannot create a Twin if the "description" field of the Twin is empty or if "department" has a different value than "sales".
Was this article helpful?