Role Policies (legacy)

📘
Enterprise Feature

Role policies allow developers to link an Application User role to a particular schema, and define the shape of the resources they can interact with. For example, a role for a device engineer that only allows them to create Thngs that have a pre-defined set of fields, and guarantee that all required properties is present.

If multiple schemas are required to be associated with a role, this can be easily achieved by creating multiple policies for that same role.

📘
Note
Once created, policies cannot be updated. You must delete the original policy and create a new one with the new data.

API Status
General Availability:
/roles/:roleId/policies

Jump To ↓

PolicyDocument Data Model
Create a Policy
Read all Policies
Read a Policy
Delete a Policy

PolicyDocument Data Model

.schema (string, read-only)
    ID of the schema to apply to this role.

.id (string, read-only)
    The ID of this resource.

.createdAt (integer, read-only)
    Timestamp when the resource was created.

.role (string, read-only)
    ID of the role this policy applies to.

{
  "type": "object",
  "description": "Object representing a role policy.",
  "properties": {
    "schema": {
      "type": "string",
      "description": "ID of the schema to apply to this role.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "createdAt": {
      "type": "integer",
      "description": "Timestamp when the resource was created.",
      "readOnly": true,
      "minimum": 0
    },
    "role": {
      "type": "string",
      "description": "ID of the role this policy applies to.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    }
  }
}

{
  "schema": "U3qcEeh9qQ9BhPaRahAXKPsm",
  "id": "Um8f62yBeMPrQ7waRFTSpc6p",
  "createdAt": 1508231204076,
  "role": "59b8f735d3fa773000b27691"
}

Create a Policy

Create a new policy to link a role with a schema.

POST /roles/:roleId/policies
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

PolicyDocument

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/roles/592d70418c5e3f2800408a74/policies' \
  -d '{
    "schema": "UmB5GSEqBD8w95aRwFWrmEph"
  }'

const roleId = '593fa5dd7acb792c000223b5';
const policy = { 
  schema: 'UGBHm6BFVDsaQKRwaFCrGhmp'
};

operator.role(roleId).policy().create(policy).then(console.log);

HTTP/1.1 201 Created
Content-Type: application/json

{
  "schema": "UGBHm6BFVDsaQKRwaFCrGhmp",
  "id": "UGBKmeNEBDPa9pRaa2CN3Epk",
  "createdAt": 1498125527441,
  "role": "593fa5dd7acb792c000223b5"
}

Read all Policies

Read all policies associated with a role. The result may be paginated if there are more than 30 items.

GET /roles/:roleId/policies
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://api.evrythng.com/roles/592d70418c5e3f2800408a74/policies'

const roleId = '593fa5dd7acb792c000223b5';

operator.role(roleId).policy().read().then(console.log);

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

[
  {
    "schema": "UmB5GSEqBD8w95aRwFWrmEph",
    "id": "UGBKmeNEBDPa9pRaa2CN3Epk",
    "createdAt": 1498125527441,
    "role": "593fa5dd7acb792c000223b5"
  }
]

Read a Policy

Read a single policy by ID.

GET /roles/:roleId/policies/:policyId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://api.evrythng.com/roles/592d70418c5e3f2800408a74/policies/UGBKmeNEBDPa9pRaa2CN3Epk'

const roleId = '593fa5dd7acb792c000223b5';
const policyId = 'UmfeqsrXBMs7QraRaE2ysqmk';

operator.role(roleId).policy(policyId).read().then(console.log);

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

{
  "schema": "UmB5GSEqBD8w95aRwFWrmEph",
  "id": "UGBKmeNEBDPa9pRaa2CN3Epk",
  "createdAt": 1498125527441,
  "role": "592d70418c5e3f2800408a74"
}

Delete a Policy

Delete a policy by ID.

DELETE /roles/:roleId/policies/:policyId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://api.evrythng.com/roles/592d70418c5e3f2800408a74/policies/UGBKmeNEBDPa9pRaa2CN3Epk'

const roleId = '593fa5dd7acb792c000223b5';
const policyId = 'UmfeqsrXBMs7QraRaE2ysqmk';

operator.role(roleId).policy(policyId).delete().then(() => console.log('Deleted'));

HTTP/1.1 204 No Content