Roles and Permissions (v2)

When an account is shared with other operators, it is possible to define and assign roles to
these operators in order to control their access rights. Each Operator can have multiple unique roles assigned to them at any one time.
In addition, the account owner can define roles for Access Tokens, assign these roles, and set permissions on individual resources.

📘

What happens if an API key has no roles assigned?

If an API key does not have roles assigned, it will not be able to access any resource in the platform.

Roles are represented as access policies in the platform. The Access Policies API allows developers to create an entirely personalised RBAC system on their accounts. See Access Policies in the API Reference section for API examples of creating and updating roles and permissions.


Predefined Roles

There is a group of predefined roles available to all accounts. Is is not possible to delete or change these roles through the API, and they are all named with an evt: prefix:

  • evt:accountAdmin- Allows general access to all resources including creating custom roles.
  • evt:globalRead - Read Access to All Resources.
  • evt:factoryAdmin - Allows user to manage access to the platform in the factory.
  • evt:factoryUser - Allows user to sign into factory activation application.
  • evt:webApplication - Anonymous web access for scanning Products and Thngs.
  • evt:brandInspector - Allows user to sign into the Authenticate application.
  • evt:brandProtector - Allows users to authenticate products and view brand protection events.
  • evt:supplyChain - Allows users to perform supply chain traceability searches.
  • evt:systemIntegrator - Used By Systems Integrators to integrate with the Evrythng Platform

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


Custom Roles

In addition to the predefined roles, the account admin (alone) can define new custom roles within the account that make more sense within the context of the application. For example, a product manufacturing company may decide to create the "machineOperator" and "shopManager" roles. These roles can then be assigned permissions allowing them to view and interact with only specific resources that they are concerned with, for example:

{
  "name": "shopManager",
  "permissions"[
    "actions:create,read,list",
    "scans:read,list",
    "products:read,list",
    "thngs:read",
  ],
}

Role Permissions

A role is defined by a list of permissions. The Operator with the evt:accountAdmin role defines and updates permissions that are associated with a given role. Thus, each Operator (and their associated API key) will inherit these permissions if they are assigned that role. Therefore, 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, a permission to allow an Operator to read and create thngs in the platform is a permission that allows read and create operations on the thngs resource. This is represented in the following format : thngs:read,create.

See Access Policies in the API Reference section to learn more about permissions, resources and operations and for API examples of creating and managing roles and permissions.


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 making use of 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. In order 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"
    ],
    "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"
     ],
    "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"
    ],
    "createdAt": 1578990823106,
      "updatedAt": 1584711547344,
      "tags": [],
      "identifiers": {},
      "customFields": {}
  }
]

The same way Operators can assign roles to other Operators, they can also do so to Access Tokens.
See Operator Access and Access Tokens in the API Reference section to learn how to manage their roles.

Updated 3 months ago


Roles and Permissions (v2)


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.