Roles and Permissions

You can define and assign roles to each Operator in an account to control their access rights. Each Operator can have multiple unique roles assigned to them.

The account owner can also define roles for Access Tokens, assign those roles, and set permissions on individual resources.

📘

What happens if an API key has no roles assigned?

If an API key doesn't have roles assigned, it can't access any resource on the Platform.

Roles are represented as access policies on the EVRYTHNG Platform. The Access Policies API lets developers create a personalized role-based access control (RBAC) system for their accounts. See Access Policies for examples of creating and updating roles and permissions using the API.

Predefined Roles

A group of predefined roles is available to all accounts. You can't delete or change these roles, and they are all named with an evt: prefix. Here are some examples:

• evt:accountAdmin- Allows general access to all resources, including creating custom roles.
• evt:consumerEngagement- Allows users to view Amplify consumer engagement metrics.
• evt:enterpriseRead - Read Access to All Resources.
• evt:factoryAdmin - Allows users to manage access to the platform in the factory.
• evt:factoryUser - Allows users to sign into factory activation application.
• evt:webApplication - Anonymous web access for scanning Products and Thngs.
• evt:brandIntegrity - Allows users to authenticate products and view brand integrity events.
• evt:brandInspector - Allows users to authenticate products.
• evt:systemsIntegration - Used By Systems Integrators to integrate with the Evrythng Platform
• evt:epcisApplication - Access for apps that scan Products and Thngs and capture EPCIS events
• evt:validateConsumerEngagement - Allows users to view consumer insights.
• evt:validateBrandIntegrity - Allows users to authenticate products using the brand integrity app and view brand integrity events.
• evt:supplyChainManager - Allows users to view supply chain custom dashboards.

When an account is created, evt:accountAdmin is the default role assigned to the first Operator on that account.

You can get an up-to-date set of default roles by using the Access Policies API, or by navigating to the roles section on the Platform.

Custom Roles

Besides the predefined roles, the account admin (alone) can define new custom roles within the account that better suit the application. For example, a product manufacturing company creates the "machineOperator" and "shopManager" roles. These roles can then be assigned permissions that allow them to view and interact with specific resources. For example:

{
  "name": "Shop Manager",
  "permissions"[
    "actions:create,read,list",
    "scans:read,list",
    "products:read,list",
    "thngs:read",
  ],
  "uiPermissions": [
    "consumerEngagement"
  ]  
}

Role Permissions

A list of permissions defines a role. The Operator with the evt:accountAdmin role defines and updates permissions that are associated with a specific role. Each Operator (and their associated API key) inherits these permissions if they are assigned that role. If the role permissions are updated, all concerned Operators accesses are consequently changed too.

Role permissions are a combination of a resource name and the allowed operations on that resource.

For example, permission to let an Operator read and create Thngs on the Platform allows read and create operations on the thngs resource. This is represented in the following format : thngs:read,create.

See Access Policies to learn more about permissions, resources and operations. That topic includes examples of creating and managing roles and permissions using the API.

Managing Operators and their Roles

The API for managing Operators is Operator Access. Any Operator allowed to manage other operator accesses can assign or remove roles to their subordinates by using the API.

For example, a factory admin can assign the Factory User role to another Operator by:

PUT /accounts/:accountId/operatorAccess/:operatorAccessId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

{
  "policies": [
    "$FACTORY_USER_ROLE_ID"
  ]
}

The API to manage roles is Access Policies. To get a list of all available roles, Operators must use the accessPolicies API:

GET /accessPolicies

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "UPb7Eq8hwpktcaaabfahfpdq",
	  "name": "evt:factoryAdmin",
	  "description": "Allows user to manage access to the platform in the factory",
	  "permissions": [
      "accounts:read,update",
      "accessPolicies:read,list",
      (...)
      "purchaseOrders:read,list",
      "purchaseOrdersAggregations:list"
    ],
    "uiPermissions": [],
    "createdAt": 1578990823106,
	  "updatedAt": 1584711547344,
	  "tags": [],
	  "identifiers": {},
	  "customFields": {}
  },
  {
 	  "id": "UsSNYMPhapktcaaabfahfpdp",
	  "name": "evt:factoryUser",
	  "description": "Allows user to sign into factory activation application",
	  "permissions": [
      "accounts:read,update",
      "products:read",
      "purchaseOrders:read,list",
      "thngs:read",
      "thngsCommissioning:create,list",
      "thngsCommissioningState:read"
     ],
    "uiPermissions": [],     
    "createdAt": 1578990823106,
	  "updatedAt": 1584711547344,
	  "tags": [],
	  "identifiers": {},
	  "customFields": {}
  },
  {
    "id": "UsbNEMshwpktcaaabfahfpdn",
	  "name": "evt:webApplication",
	  "description": "Anonymous web access for scanning Products and Thngs",
	  "permissions": [
      "applications:read",
      "places:read",
      (...)
      "thngsActions:read,create,list",
      "scan:read"
    ],
    "uiPermissions": [],    
    "createdAt": 1578990823106,
	  "updatedAt": 1584711547344,
	  "tags": [],
	  "identifiers": {},
	  "customFields": {}
  }
]

Operators can assign roles to Access Tokens. See Operator Access and Access Tokens to learn how to manage roles.