Role Permissions (legacy)

Role permissions determine what an Operator or Application User can see/do on an account according to their assigned role. Read the Roles section for more information on managing roles through the API.

Read Roles and Permissions in the Documentation section for more conceptual information on roles and permissions usage.

📘
Note
If a role's permissions are changed while a user with that role has an open Pub/Sub Broker connection, the changes will not apply for those users until they disconnect and reconnect.

API Status
General Availability:
/roles/:roleId/permissions
/roles/:roleId/permission/:permissionName

Jump To ↓

Operator Role Permissions
Application User Role Permissions

Operator Role Permissions

Jump To ↓

OperatorRolePermissionDocument Data Model
Enable/Disable an Operator Role Permission
Enable/Disable a Project-scoped Operator Role Permission
Read an Operator Role's Permissions

OperatorRolePermissionDocument Data Model

.name (string, required, one of 'global_read', 'gl_resource_update', 'gl_project_update', 'project_read', 'project_update', 'project_resource_update')
    Name of the specific role permission.

.enabled (boolean, required)
    `true` if this permission is enabled, `false` otherwise.

.projectScoped (boolean, read-only)
    `true` if this permission if enabled only for specific 
    project(s), `false` otherwise.

.projects (array of string)
    Array of project IDs that this permission is enabled for.

.children (string)
    Object describing Operator role permissions

{
  "type": "string",
  "description": "Object describing Operator role permissions",
  "properties": {
    "name": {
      "type": "string",
      "description": "Name of the specific role permission.",
      "enum": [ "global_read", "gl_resource_update", "gl_project_update", "project_read", "project_update", "project_resource_update" ]
    },
    "enabled": {
      "type": "boolean",
      "description": "`true` if this permission is enabled, `false` otherwise."
    },
    "projectScoped": {
      "type": "boolean",
      "description": "`true` if this permission if enabled only for specific project(s), `false` otherwise.",
      "readOnly": true
    },
    "projects": {
      "type": "array",
      "description": "Array of project IDs that this permission is enabled for.",
      "items": {
        "type": "string",
        "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
      }
    },
    "children": {
      "$ref": "OperatorRolePermissionDocument",
      "readOnly": true
    }
  }
}

[
  {
    "name": "global_read",
    "enabled": false,
    "projectScoped": false,
    "children": [
      {
        "name": "gl_resource_update",
        "enabled": false,
        "projectScoped": false
      },
      {
        "name": "gl_project_update",
        "enabled": false,
        "projectScoped": false
      }
    ]
  },
  {
    "name": "project_read",
    "enabled": false,
    "projectScoped": true,
    "projects": [],
    "children": [
      {
        "name": "project_update",
        "enabled": false,
        "projectScoped": true,
        "projects": []
      },
      {
        "name": "project_resource_update",
        "enabled": false,
        "projectScoped": true,
        "projects": []
      }
    ]
  }
]

Enable/Disable an Operator Role Permission

Enable or disable a specific permission for a given Operator role. Set enabled to true to grant that permission, false to revoke it.

PUT /roles/:roleId/permissions/:permissionName
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

OperatorRolePermissionDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/roles/UhpHrg39QCy9dsSddN8xhwnb/permissions/global_read' \
  -d '{ 
    "name": "global_read", 
    "enabled": true 
  }'

const roleId = '59aeb3abb24413002c7d8651';
const name = 'global_read';
const payload = { name, enabled: true };

operator.role(roleId).permission(name)
  .update(payload)
  .then(console.log);

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

{ 
  "name": "global_read", 
  "enabled": true, 
  "projectScoped": false 
}

Enable/Disable a Project-scoped Operator Role Permission

PUT /roles/:roleId/permissions/:permissionName

For project_* type permissions, it is also possible to specify which projects the permission applies to. For example, to enable the project_read permission for a single project include an array of project IDs in the projects field of the request:

PUT /roles/:roleId/permissions/:permissionName
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

OperatorRolePermissionDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/roles/5805f5012229bd50693aac24/permissions/project_read' \
  -d '{ 
    "name": "project_read", 
    "enabled": true,
    "projects": [ "Uh5qRBqc4DcmbNbAANtMnrYm" ]
  }'

const roleId = '59aeb3abb24413002c7d8651';
const name = 'project_read';
const payload = { 
  name, 
  enabled: true,
  projects: ['Uh5qRBqc4DcmbNbAANtMnrYm'],
};

operator.role(roleId).permission(name)
  .update(payload)
  .then(console.log);

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

{ 
  "name": "project_read", 
  "enabled": true, 
  "projectScoped": true, 
  "projects": [ "Uh5qRBqc4DcmbNbAANtMnrYm" ] 
}

Read an Operator Role's Permissions

Read the state of all permission types for a given role. In the case of reading all permissions for an Operator type role the following response is returned, containing the state of all permissions for that role.

Since it is a collection of OperatorRolePermissionDocument objects, the fields themselves are the same as detailed in the OperatorRolePermissionDocument section above.

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

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://api.evrythng.com/roles/5805f5012229bd50693aac24/permissions'

const roleId = '5805f5012229bd50693aac24';

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

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

[
  {
    "name": "global_read",
    "enabled": false,
    "projectScoped": false,
    "children": [
      {
        "name": "gl_resource_update",
        "enabled": false,
        "projectScoped": false
      }, 
      {
        "name": "gl_project_update",
        "enabled": false,
        "projectScoped": false
      }
    ]
  }, 
  {
    "name": "project_read",
    "enabled": false,
    "projectScoped": true,
    "projects": [],
    "children": [
      {
        "name": "project_update",
        "enabled": false,
        "projectScoped": true,
        "projects": []
      }, 
      {
        "name": "project_resource_update",
        "enabled": false,
        "projectScoped": true,
        "projects": []
      }
    ]
  }
]

Application User Role Permissions

The Application User role permissions model is similar to that used for Operator roles, with one key difference: each role has a set of permissions that can be added or removed, instead of enabled or disabled. The set of paths and access modes a role has determines the resources it can see and interact with. See the ApplicationUserRolePermissionDocument Data Model section for how to specify this.

Jump To ↓

ApplicationUserRolePermissionDocument Data Model
Update an Application User Role's Permissions
Delete an Application User Role's Permissions
Read an Application User Role's Permissions
Default Application User Role Permissions

ApplicationUserRolePermissionDocument Data Model

This object details a single role permission's path and access methods available to an Application User who is assigned this role. See the Base App User Role Permissions section for a list of available options.

.path (string, required)
    The API path the role can access. Must be a subset of the 
    default `base_app_user` permissions.

.access (string, required)
    A four letter combination of 'c', 'r', 'u', and 'd' 
    describing the access to create, read, update, or destroy 
    the resources in the 'path' of this permission.

.default (boolean, read-only)
    `true` for default permissions.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object representing an account role permission. Depending on the type of role, different fields may be returned.",
  "required": ["path", "access"],
  "properties": {
    "path": {
      "type": "string",
      "description": "The API path the role can access. Must be a subset of the default `base_app_user` permissions."
    },
    "access": {
      "type": "string",
      "description": "A four letter combination of 'c', 'r', 'u', and 'd' describing the access to create, read, update, or destroy the resources in the 'path' of this permission.",
      "minLength": 1,
      "maxLength": 4
    },
    "default": {
      "type": "boolean",
      "description": "`true` for default permissions.",
      "readOnly": true
    }
  }
}

[
  {
    "path": "/access$",
    "access": "r",
    "default": true
  },
  {
    "path": "/accesses",
    "access": "crd",
    "default": true
  },
  {
    "path": "/auth/all/logout",
    "access": "c",
    "default": true
  },
  {
    "path": "/rateLimits$",
    "access": "r",
    "default": true
  },
  {
    "path": "/roles",
    "access": "r",
    "default": true
  },
  {
    "path": "/thngs",
    "access": "cru"
  },
  {
    "path": "/products",
    "access": "cru"
  },
  {
    "path": "/collections",
    "access": "cru"
  },
  {
    "path": "/collections/*/thngs/*",
    "access": "d"
  },
  {
    "path": "/actions/*",
    "access": "cr"
  },
  {
    "path": "/actions",
    "access": "r"
  },
  {
    "path": "/auth/evrythng/thngs",
    "access": "crd"
  },
  {
    "path": "/users/{user}",
    "access": "ru"
  },
  {
    "path": "/places",
    "access": "r"
  },
  {
    "path": "/connectors/*/auth",
    "access": "rd"
  },
  {
    "path": "/connectors/*/auth/token",
    "access": "c"
  },
  {
    "path": "/connectors",
    "access": "r"
  }
]

Update an Application User Role's Permissions

Use a PUT request to replace the role's current set of permissions with a new set.

To remove a permission, simply omit it in the payload after reading from the role initially.

🚧
Permissions are replaced
This request must include any existing permissions, otherwise they will be deleted if not present in the new payload.

PUT /roles/:roleId/permissions
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

[ ApplicationUserRolePermissionDocument, ... ]

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/roles/5805f5012229bd50693aac24/permissions' \
  -d '[
    {
      "path": "/thngs",
      "access": "cr"
    }
  ]'

const roleId = '5805f5012229bd50693aac24';
const payload = [{ path: '/thngs', access: 'cru' }];

operator.role(roleId).permission()
  .update(payload)
  .then(console.log);

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

[
  {
    "path": "/thngs",
    "access": "cru"
  }
]

Read an Application User Role's Permissions

Read an array of paths and access types that an Application User with the specified role can access.

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

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://api.evrythng.com/roles/593e8f3fcfe9a42c00bf1434/permissions'

const roleId = '593e8f3fcfe9a42c00bf1434';

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

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

[
  {
    "path": "/thngs",
    "access": "cru"
  },
  {
    "path": "/products",
    "access": "cru"
  }
]

Delete an Application User Role's Permissions

To delete all non-default permissions for an Application User role, simple perform an update with an empty array payload ([]).

PUT /roles/:roleId/permissions
Authorization: $OPERATOR_API_KEY

[]

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/roles/5805f5012229bd50693aac24/permissions' \
  -d '[]'

const roleId = '592d70418c5e3f2800408a74';

// Set to zero permissions
const payload = [];

operator.role(roleId).permission()
  .update(payload)
  .then(console.log);

Default Application User Role Permissions

When a new Application User role is created, it inherits some immutable permissions that all users in that role will get. These are identified by the default field. Any additional permissions the role requires can be added in addition to these default permissions:

[
  {
    "path": "/access$",
    "access": "r",
    "default": true
  },
  {
    "path": "/accesses",
    "access": "crd",
    "default": true
  },
  {
    "path": "/auth/all/logout",
    "access": "c",
    "default": true
  }, 
  {
    "path": "/rateLimits$",
    "access": "r",
    "default": true
  }, 
  {
    "path": "/roles",
    "access": "r",
    "default": true
  }
]

Base App User Role Permissions

The base_app_user role has the following set of permissions, from which each custom role may choose.

[
  {
    "path": "/access$",
    "access": "r",
    "default": true
  },
  {
    "path": "/accesses",
    "access": "crd",
    "default": true
  },
  {
    "path": "/auth/all/logout",
    "access": "c",
    "default": true
  },
  {
    "path": "/rateLimits$",
    "access": "r",
    "default": true
  },
  {
    "path": "/roles",
    "access": "r",
    "default": true
  },
  {
    "path": "/thngs",
    "access": "cru"
  },
  {
    "path": "/thngs/*",
    "access": "cru"
  },
  {
    "path": "/products",
    "access": "cru"
  },
  {
    "path": "/products/*",
    "access": "cru"
  },
  {
    "path": "/collections",
    "access": "cru"
  },
  {
    "path": "/collections/*",
    "access": "cru"
  },
  {
    "path": "/collections/*/thngs/*",
    "access": "d"
  },
  {
    "path": "/actions/*",
    "access": "cr"
  },
  {
    "path": "/actions",
    "access": "r"
  },
  {
    "path": "/auth/evrythng/thngs",
    "access": "crd"
  },
  {
    "path": "/users/{user}",
    "access": "ru"
  },
  {
    "path": "/places",
    "access": "r"
  },
  {
    "path": "/places/*",
    "access": "r"
  },
  {
    "path": "/connectors/*/auth",
    "access": "rd"
  },
  {
    "path": "/connectors/*/auth/token",
    "access": "c"
  },
  {
    "path": "/connectors",
    "access": "r"
  },
  {
    "path": "/ifttt/v1",
    "access": "crd"
  },
  {
    "path": "/auth/oauth2",
    "access": "cr"
  },
  {
    "path": "/cujo",
    "access": "c"
  },
  {
    "path": "/thngs/*/actions/commissions",
    "access": "cr"
  },
  {
    "path": "/thngs/*/actions/decommissions",
    "access": "cr"
  },
  {
    "path": "/thngs/*/commissionState",
    "access": "r"
  }
]

Role Permissions (legacy)

📘
Note

Operator Role Permissions

Jump To ↓

OperatorRolePermissionDocument Data Model

Enable/Disable an Operator Role Permission

Enable/Disable a Project-scoped Operator Role Permission

Read an Operator Role's Permissions

Application User Role Permissions

Jump To ↓

ApplicationUserRolePermissionDocument Data Model

Update an Application User Role's Permissions

🚧
Permissions are replaced

Read an Application User Role's Permissions

Delete an Application User Role's Permissions

Default Application User Role Permissions

Base App User Role Permissions

📘Note

Operator Role Permissions

Jump To ↓

OperatorRolePermissionDocument Data Model

Enable/Disable an Operator Role Permission

Enable/Disable a Project-scoped Operator Role Permission

Read an Operator Role's Permissions

Application User Role Permissions

Jump To ↓

ApplicationUserRolePermissionDocument Data Model

Update an Application User Role's Permissions

🚧Permissions are replaced

Read an Application User Role's Permissions

Delete an Application User Role's Permissions

Default Application User Role Permissions

Base App User Role Permissions

📘
Note

🚧
Permissions are replaced