Access Control (legacy)

The EVRYTHNG Platform includes several mechanism that allow configuration of granular access to resources within any given account. These make it possible to allow effective collaboration between team members with different needs and privileges, and also provides the security required where product and user data is concerned.

By default, these features provide an intuitive degree of access that is suitable for most projects. However, for those that require more strict control of resources for access and security purposes, they are also highly customisable when combined and correctly configured. This page aims to help explain how these mechanisms work, and also how to achieve some of the most common requirements and scenarios.

The following gives a brief summary of each of the access control features available to developers to leverage in their integrations. More in-depth information can be found on the linked pages.

Multiple Types of Actor

Operators, Applications, Application Users, and Devices have different permissions for their own roles within a project. For example, an Operator has the most access (to every resource, by default), whereas an Device has the least - the single Thng it represents.

See Key Types for more information on different kinds of actor.

## Multiple Types of API Key

For each type of actor listed above, there exists a type of API key directly related to that actor. For example, each Operator collaborating as team members on a given EVRYTHNG account will have an Operator API Key that is unique per user, per account. Similarly, any Application User created within a project will have their own unique Application User API Key assigned each time they log in.

Each of these types of API keys has its own set of permissions based on what that actor is reasonably required to do. In the case of an Application User, their API key allows them to read and update only those resources within their project, within their visibility, or those that they created themselves. Similarly, an Application API Key (representing access on behalf of a web or native application) is only allowed to read project-specific resources and create new Application Users, who when manage the resources themselves.

See API Keys and Key Permissions for more information on what each kind of API key is allowed to do.

Project and User Scoping

All resources in an EVRYTHNG account are normally added to (‘scoped’ to) one or more projects, depending on their purpose. For example, a project could contain all Thngs related to a particular campaign, or region of the world they exist in. This is known as the ‘project scope’, and limits visibility of all actors specific to that project (Applications and their Application Users) to only those resources in that project. Where access is required by Applications or Application Users in separate projects, resources can be scoped to multiple projects at once.

Similarly, resources can also be scoped to all or a specific list of Application Users within any projects they are scoped to. This is known as the ‘user scope’ of that resource. By default, when a resource is created by an Application User (such as when a consumer registers their product purchase and a Thng is to be created to track its data) it is scoped only to the one who created it. If it is to be shared among multiple users within the same project, they can be added to the resource’s users scope, or the resource itself can be scoped at once to all users now, and in the future.

See Types of Scope for more information on different kind of scope.

Roles and Permissions

For both the Operator and Application User actors, various built-in and customizable roles can be assigned. Common examples of roles can include read-only access to a specific project, or access to only create and modify products but not Thngs. By default, every Operator collaborating on a team in a given account is assigned a role upon invitation. Any account Administrator can assign a new role to any other Operator as required, as well as define new roles with new specialised degrees of access.

See Operator Role Permissions for more information on how roles can shape Operator access.

Application Users can also be assigned individual roles with granular permissions according to their area of responsibility. For example, a consumer may only need access to read and update their own Thngs. Similarly, a factory worker responsible for managing products produced may need increased access to be able to view all Thngs, and create new ones.

See Application User Role Permissions for complete information on available permissions for Application User roles to have.

Sharing resources across projects

A common scenario that occurs is that resources like products (representing brand SKUs) or action types (representing common supply chain events) need to be re-used and shared between projects. If these resources were originally created in scope of a single project (either with that project selected in the Dashboard at the time, or by a project-scoped API key such as an Application User API Key), they will not be visible to any actors in another project scope.

In the case of action types, for example, any attempt to create the same one in a different project will return an error - action type names are unique across an account. Similarly, if the resources are created with no project scope at all (‘None’ project selected in the Dashboard, or by an unscoped Operator API Key request), no project-scoped actor can see them until they have been scoped to at least that actor’s project.

To facilitate this sharing of resources, use the Dashboard to assign additional projects to the resource’s scope, or remove unnecessary ones. Select one or more resources in a list and click ‘Add to project’ will perform this action. An example is shown below:

The same can be done programmatically through the API by adding a project ID to a resources projects scopes, as and when the solution requires changes to be made, such as when many resources are to be created in scope of many Application Users from different projects.

## Sharing resources with all project Application Users

In scenarios where one Application User creates a resource (a factory worker creating Thngs), it is automatically limited in its users scopes to just that user - they are the ‘owner’ of that new resource. A common requirement is that the resource is also visible to users of the resource and its data further down the road in its lifecycle, such as a purchasing consumer reading provenance or experience data.

By default, these other Application Users would not be able to see the resources created by others in the same project. The solution to this involves a special user scope - all. By adding all to a resource’s users scopes, it becomes visible and shared to all existing and future users of that resource. Currently this is only possible to effect using the API, for example for a Thng:

PUT /thngs/UMCBY4rMpHpsndaRamk8rcEk
Content-Type: application/json
Authorization: $TRUSTED_APPLICATION_API_KEY

{
  "scopes": {
    "users": ["+all"]
  }
}

Alternatively, visibility of the Thng can be shared to specific Application Users by their id:

PUT /thngs/UMCBY4rMpHpsndaRamk8rcEk
Content-Type: application/json
Authorization: $TRUSTED_APPLICATION_API_KEY

{
  "scopes": {
    "users": [
      "UqAdfnmQ5Hp8HAaaRmdaRxrp",
      "U6Cwh3eAmDxecFRww4ycVt3c",
      "UqfRhpwNc5d2EHaaw3CCdwre"
    ]
  }
}

You can inspect which projects and users scopes a resource has by including the withScopes=true query parameter in a GET request through the API:

GET /thngs/UMCBY4rMpHpsndaRamk8rcEk?withScopes=true

The response will contain scopes:

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

{
  "id": "UMYmxxhRCyQ4ttwaamaAnbTh",
  "createdAt": 1551438192901,
  "customFields": {},
  "scopes": {
    "users": [
      "all"
    ],
    "projects": [
      "U6EDmmfwfc9HtQwRamQ9bpwf"
    ]
  },
  "updatedAt": 1551438192901,
  "name": "Example Thng",
  "product": "UqEGbSBxCc9H9QwwwGRdnxbe",
  "properties": {},
  "identifiers": {
    "dm": "389467999"
  }
}

## Allowing read-only access to a project

When adding a new team member to an account so that they may access data and analytics but not make any changes, the usual approach is to create a new Operator role specifying read access and naming the specific project(s) that should be visible to Operators with the new role. An example is shown below:

Sharing specific Dashboard views

In scenarios where sharing limited access to resources or projects makes sense, it also makes sense to selectively limit the Dashboard pages such a restricted Operator can view. This can be done in the same page as before, in the ‘Visible Pages’ section, after selecting which project access the role should bestow on Operators that are assigned it.

The example configuration below shows a role that is designed for read-only access to the Places, Products, and Thngs pages to view account data, and only the commonly used Actions and Overview shared dashboard pages, which likely contain all the event and analytics data they will ever need in their limited role.

Limited access to Dashboard pages can also be configured automatically through the API, for instance during setting up a new solution based on an existing configuration. In this case, the items listed in the role’s custom fields correspond to the checkboxes in the Dashboard ‘Visible Pages’ UI.

Read the Roles page for more information on setting a role’s visibility of specific Dashboard pages.

Limiting Application User permissions

Similar to how Operators can collaborate on an account with different appropriate levels of access and visibility, so too can Application Users who play different roles within the same project. An example already illustrated earlier is the different level of access a factory manager would need to create, update, delete Thngs, products, and collections versus an end-user that only needs to see one Thng or one product. In between, a developer or account manager Application User may need to tweak the solution setup by modifying places or product metadata in response to changing requirements or market conditions.

This sort of granular access for Application Users is achieved using Application User role permissions - rules specific to them. Each access rule is governed by two criteria - the API path (such as /thngs) and the access type (such as cru for create, read, and update but not delete). An Application User automatically inherits the ‘Default Role’ assigned to the Application that creates them, or the ‘Base Application User’ default set of permissions if this hasn’t been explicitly changed. This basic set of permissions is broad, but appropriate to Application User in general that need only to access things they own and have been shared with them.

The ‘Application User Roles’ page in the Dashboard allows configuration of both of these aspects, but can also be done programmatically through the API. The example below shows an example permission set allowing only access to read and update Thng in bulk - perfect for an overview role and one that needs to make multiple changes at once through the use of filters. In this case, if the user later needs to create Thngs as well, simply checking ‘Create’ for this path will have the required outcome.