Scoping (legacy)

Resource scoping is an important concept in the EVRYTHNG Platform API. In a nutshell, a resource's scopes determines who can view and interact with it. There are multiple types of scope:

Account scope - The account a resource is created in, either by an account Operator or other actor.
Project scope - All projects that this resource is visible to, and by extension, applications and Application Users within those projects.
User scope - All Application Users that can interact with this resource.

By default, all resources are created with no project scope, which means that no Application Users or Operators with specific project permissions can view them. To grant access to more users or projects, update the scopes of the resource as described below.

The permissions for scope management are derived by the ones on the related resources e.g., if you can view and/or modify something, then you can view and/or modify its scope.

📘
Note
We recommend that all resources are scoped on creation to minimise confusion and maximise appropriate access and security.

## ScopesDocument Data Model

.users (array of string)
    An array of Application User IDs this resource is scoped to.

.projects (array of string)
    An array of project IDs this resource is scoped to.

{
  "type": "object",
  "description": "Project and user scopes arrays.",
  "properties": {
    "users": {
      "type": "array",
      "description": "An array of Application User IDs this resource is scoped to.",
      "items": { "type": "string" }
    },
    "projects": {
      "type": "array",
      "description": "An array of project IDs this resource is scoped to.",
      "items": {
        "type": "string",
        "description": "The ID of this resource.",
        "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
        "readOnly": true
      }
    }
  }
}

{
  "users": [
    "all"
  ],
  "projects": [
    "UmxHK6K8BXsa9KawRh4bTbqc",
    "U4aPM5gyBg8w9pwaaYKCepVg"
  ]
}

Read Resource Scopes

Requests that return resources will not display the resource scopes by default. In order to view the scopes property, ?withScopes query parameter should be set to true. For example:

GET /products?withScopes=true
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://api.evrythng.com/products?withScopes=true'

const params = { withScopes: true };
operator.product().read({ params })
  .then(console.log);

// Or using param setters
operator.product().setWithScopes()
  .read()
  .then(console.log);

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

[
  {
    "id": "Umnfh3EUBMP7tNaaRmQREhRa",
    "createdAt": 1504016755599,
    "name": "Temperature Sensor Product",
    "fn": "Temperature Sensor Product",
    "description": "A standard temperature sensor",
    "scopes": {
      "users": [
        "U3ng82wQBqPrtNRwwmQwkt8d"
      ],
      "projects": [
        "UG4WExTKBqPr9NwRa3twYDnk"
      ]
    },
    "updatedAt": 1505383000034,
    "properties": {
      "on_duration_seconds": 3343,
      "temperature_celsius": 42
    }
  }
]

## Update Resource Scopes

The scope of resources can be edited with an update (PUT) request containing a new scopes property with a list of the Application Users and/or projects to be scoped. For example, to update a Thng's scopes:

PUT /thngs/:thngId
Authorization: $OPERATOR_API_KEY
Content-Type: application/json

{
  "scopes": ScopesDocument
}

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/thngs/Um2eFEyqBD8w95wwRgkB5cbc' \
  -d '{
    "scopes": {
      "users": [ "UmWA65MTeD8wQKRwwh9VHyrn" ],
      "projects": [ "Umnfh3EUBMP7tNaaRmQREhRa" ]
    }
  }'

const thngId = 'Um2eFEyqBD8w95wwRgkB5cbc';

const projects = ['Umnfh3EUBMP7tNaaRmQREhRa'];
const users = ['UmWA65MTeD8wQKRwwh9VHyrn'];

// Using rescope method
operator.thng(thngId)
  .rescope(projects, users)
	.then(console.log);

// Or using PUT payload
operator.thng(thngId)
  .update({
    scopes: {
      projects,
      users,
    }
  })
  .then(console.log);

By default, the operation will replace the scopes of the resource being updated with those in the request. To add or remove an ID, simply prefix it with the + or - character respectively. For example, to only add a single project ID and add all Application Users:

PUT /thngs/:thngId
Authorization: $OPERATOR_API_KEY
Content-Type: application/json

{
  "scopes": {
    "projects": ["+Umnfh3EUBMP7tNaaRmQREhRa"],
    "users": ["+all"]
  }
}

Additionally the keyword all can be used in place of the named projects and users IDs.

Scope a Resource on Creation

Resources should be scoped to a project on creation by passing the desired project ID in the project parameter. This is a recommended practise when creating resource as it ensures that they are scoped appropriately from the earliest opportunity.

POST /thngs?project=:projectId
Authorization: $OPERATOR_API_KEY
Content-Type: application/json

{
  "name": "Automatically Scoped Thng"
}

curl -x -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/thngs?project=UmFBemNbMmPEY6awwDfxYgxh'
  -d '{ 
    "name": "Automatically Scoped Thng" 
  }'

const projectId = 'UmFBemNbMmPEY6awwDfxYgxh';
const payload = { name: 'Automatically Scoped Thng' };

const params = { project: projectId };
user.thng().create(payload, { params }).then(console.log);

// Or using param setters
user.thng().setProject(projectId)
  .create(payload)
  .then(console.log);

String projectId = "Uh5qRBqc4DcmbNbAANtMnrYm";

Thng thng = new Thng();
thng.setName("Automatically Scoped Thng");
apiManager.thngService().thngCreator(thng).project(projectId).execute();

📘Note

Read Resource Scopes

Scope a Resource on Creation

📘
Note