ActivateAuthenticateAmplify
DashboardSupportDeveloper Blog

Roles (legacy)

When an account is shared with other team members (as Operators), it is possible to define and assign custom roles in order to control their access rights. Each Operator can only have a single Operator role assigned to them at any one time. In addition, the account owner Operator can define roles for Application Users, assign these roles to applications, and set permissions on individual resources and operations.

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

API Status
General Availability:
/roles
/roles/:roleId
/accounts/:accountId/accesses
/accounts/:accountId/accesses/:accessId

Jump To ↓

Operator Roles
Application User Roles
Read all Roles
Delete a Role
Update a Role's Project Scope
Set a Role's Scoped Roles
Read a Role's Scoped Roles
Read an Account's Role
Set an Account's Role
Application Default Role

Operator Roles

Jump To ↓

OperatorRoleDocument Data Model
Create an Operator Role
Read an Operator Role
Update an Operator Role

OperatorRoleDocument Data Model

The OperatorRoleDocument contains the basic information about a role, as well as the allowed permissions if set.

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

.name (string, required)
    Friendly name of this resource.

.description (string)
    Friendly description of this resource.

.customFields (CustomFieldsDocument)
    Object of case-sensititve key-value pairs of custom fields
    associated with the resource.

{
  "additionalProperties": false,
  "type": "object",
  "description": "Object representing an Operator role.",
  "required": ["name"],
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "name": {
      "type": "string",
      "description": "Friendly name of this resource."
    },
    "description": {
      "type": "string",
      "description": "Friendly description of this resource."
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    }
  }
}

{
  "id": "5a0ece3ec1527b00300cc9a5",
  "name": "Data Analyst",
  "description": "Role for all Data Analyst Operators."
}

A table of possible values for customFields.enabledStates is shown below:

ValueRole can view...
appAll pages
app.dashboardsAll dashboards
app.dashboards.actionsActions dashboard
app.dashboards.overviewOverview dashboard
app.dashboards.usersUsers dashboard
app.projectsAll projects
app.redirectorRedirector dashboard
app.resourcesAll types of platform resources
app.resources.actiontypesAction Types dashboard
app.resources.batchesBatches dashboard
app.resources.collectionsCollections dashboard
app.resources.productsProducts dashboard
app.resources.thngsThngs dashboard
app.testingTesting dashboard
app.userDashboardsMy Dashboards section

Create an Operator Role

Roles are created with a POST request to the /roles resource containing a JSON document.

🚧

Notes

Only the account owner can create new roles.

You cannot create roles with the same name as the predefined admin and none roles.

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

OperatorRoleDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/roles' \
  -d '{
    "name" : "Data Analyst",
    "description" : "Role for all Data Analyst Operators."
  }'

const payload = {
  name: 'Data Analyst',
  description: 'Role for all Data Analyst Operators.',
};

operator.role().create(payload)
  .then(console.log);

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

{
  "id": "5901c5d4b14d6d2c00dc420d",
  "name" : "Data Analyst",
  "description" : "Role for all Data Analyst Operators."
}

Read an Operator Role

Read a single Operator role by ID.

GET /roles/:roleId
Authorization: $OPERATOR_API_KEY

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

const roleId = '593e8f3fcfe9a42c00bf1434';

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

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

{
  "id": "593e8f3fcfe9a42c00bf1434",
  "name": "Data Analyst",
  "description": "Role for all Data Analyst Operators."
}

Update an Operator Role

Update an Operator role with a PUT request to the /roles/:roleId resource containing a JSON document that is some subset of the OperatorRoleDocument. For example, just a new description field.

🚧

Note

Once a role has been created, its type cannot be updated.

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

OperatorRoleDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/roles/58cfc58d085b262800b78183' \
  -d '{
    "description": "Role for all Data Analyst Operators."
  }'

const roleId = '58cfc58d085b262800b78183';
const payload = {
  description: 'Role for all Data Analyst Operators.',
};

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

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

{
  "id": "58cfc58d085b262800b78183",
  "name": "Data Analyst",
  "description": "Role for all Data Analyst Operators."
}

Application User Roles

In addition to account-level Operator roles, Application Users can be assigned Application User roles that dictate which resources they can view and interact with.

New Application User roles automatically inherit some default immutable permissions. See the Role Permissions page for more information.

Jump To ↓

ApplicationUserRoleDocument Data Model
Create an Application User Role
Read an Application User Role
Update an Application User Role
Application Default Role

ApplicationUserRoleDocument Data Model

.name (string, required)
    Friendly name of this resource.

.id (string, read-only)
    The role ID. May alse be 'none', 'admin', or 'base_app_user' 
    default roles.

.type (string, one of 'userInApp')
    The type of Role. Only 'userInApp' is currently available.

.version (integer, one of '2')
    The Role API version.

.description (string)
    Friendly description of this resource.

.customFields (CustomFieldsDocument)
    Object of case-sensititve key-value pairs of custom fields 
    associated with the resource.

.scopes (RoleScopesDocument)
    The roles and projects scopes this role is scoped to.

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

.updatedAt (integer, read-only)
    Timestamp when the resource was updated.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object describing a Platform role.",
  "required": ["name"],
  "properties": {
    "name": {
      "type": "string",
      "description": "Friendly name of this resource."
    },
    "id": {
      "type": "string",
      "description": "The role ID. May alse be 'none', 'admin', or 'base_app_user' default roles.",
      "readOnly": true,
      "minLength": 4,
      "maxLength": 24
    },
    "type": {
      "type": "string",
      "description": "The type of Role. Only 'userInApp' is currently available.",
      "enum": ["userInApp"]
    },
    "version": {
      "type": "integer",
      "description": "The Role API version.",
      "enum": [2]
    },
    "description": {
      "type": "string",
      "description": "Friendly description of this resource."
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    },
    "scopes": {
      "additionalProperties": false,
      "type": "object",
      "description": "The roles and projects scopes this role is scoped to.",
      "required": ["roles", "projects"],
      "properties": {
        "roles": {
          "type": "array",
          "description": "The roles this role is scoped to.",
          "items": {
            "type": "string",
            "description": "The ID of this resource.",
            "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
            "readOnly": true
          }
        },
        "projects": {
          "type": "array",
          "description": "The projects this role is scoped to.",
          "items": {
            "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
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    }
  }
}

{
  "id": "59b8f735d3fa773000b27691",
  "version": 2,
  "type": "userInApp",
  "name": "Brand Inspector",
  "description": "A role for all Brand Inspector Application Users",
  "createdAt": 1505294133126,
  "updatedAt": 1510920016139
}

RoleScopesDocument Data Model

.roles (array of string, required)
    The roles this role is scoped to.

.projects (array of string, required)
    The projects this role is scoped to.

{
  "additionalProperties": false,
  "type": "object",
  "description": "The roles and projects scopes this role is scoped to.",
  "required": ["roles", "projects"],
  "properties": {
    "roles": {
      "type": "array",
      "description": "The roles this role is scoped to.",
      "items": {
        "type": "string",
        "description": "The ID of this resource.",
        "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
        "readOnly": true
      }
    },
    "projects": {
      "type": "array",
      "description": "The projects this role is scoped to.",
      "items": {
        "type": "string",
        "description": "The ID of this resource.",
        "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
        "readOnly": true
      }
    }
  }
}

Create an Application User Role

🚧

Notes

Only the account owner can create new roles.

You cannot create roles with the same name as the predefined admin and none roles.

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

AppUserRoleDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/roles' \
  -d '{
    "type": "userInApp",
    "version": 2,
    "name" : "Brand Inspector",
    "description" : "A role for all Brand Inspector Application Users"
  }'

const payload = {
  type: 'userInApp',
  version: 2,
  name: 'Brand Inspector',
  description: 'A role for all Brand Inspector Application Users',
};

operator.role().create(payload)
  .then(console.log);

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

{
  "id": "58d014554451ac280060f2db",
  "type": "userInApp",
  "version": 2,
  "name": "Brand Inspector",
  "description": "A role for all Brand Inspector Application Users",
  "createdAt": 1490031701138,
  "updatedAt": 1490031701138
}

Read an Application User Role

Read a single Application User role by ID.

GET /roles/:roleId
Authorization: $OPERATOR_API_KEY

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

const roleId = '593e8f3fcfe9a42c00bf1434';

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

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

{
  "id": "593e8f3fcfe9a42c00bf1434",
  "type": "userInApp",
  "version": 2,
  "name": "Brand Inspector",
  "description": "A role for all Brand Inspector Application Users",
  "createdAt": 1490031701138,
  "updatedAt": 1490031701138
}

Update an Application User Role

Update a role with a PUT request to the /roles/:roleId resource containing a JSON document that is some subset of the RoleDocument. For example, just a new description field.

🚧

Note

Once a role has been created, its type cannot be updated.

When updating customFields the entire object is replaced with the copy in the request payload.

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

AppUserRoleDocument (subset)

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/roles/58cfc58d085b262800b78183' \
  -d '{
    "description": "A role for all Brand Inspector Application Users in Europe."
  }'

const roleId = '58cfc58d085b262800b78183';
const payload = {
  description: 'A role for all Brand Inspector Application Users in Europe.',
};

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

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

{
  "id": "58cfc58d085b262800b78183",
  "type": "userInApp",
  "version": 2,
  "name": "Brand Inspector",
  "description": "A role for all Brand Inspector Application Users in Europe.",
  "createdAt": 1490011533066,
  "updatedAt": 1490011533066
}

Read all Roles

Get a list of all available roles for the account. The result may be paginated if there are more than 30 items.

GET /roles
Authorization: $OPERATOR_API_KEY

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

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

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

[
  {
    "id": "admin",
    "name": "admin"
  },
  {
    "id": "none",
    "name": "none"
  },
  {
    "id": "base_app_user",
    "version": 2,
    "type": "userInApp",
    "name": "base_app_user"
  },
  {
    "id": "592d70418c5e3f2800408a74",
    "version": 2,
    "type": "userInApp",
    "name": "Brand Inspector",
    "description": "A role for all Brand Inspector Application Users",
    "createdAt": 1496150081776,
    "updatedAt": 1496150097386
  },
  {
    "id": "592d70a18c5e3f2800408ab3",
    "name": "Data Analyst",
    "description": "A role for all Data Analyst Operators."
  }
]

Delete a Role

Remove a single role of either type by performing a DELETE request on the /roles/:roleId resource.

🚧

Note

The predefined none role will be assigned to all the users currently having the role about to be removed.

A userInApp role cannot be deleted until all users with that role have been assigned a different role.

DELETE /roles/:roleId
Authorization: $OPERATOR_API_KEY

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://api.evrythng.com/roles/58cfc58d085b262800b78183'

const roleId = '5805f5012229bd50693aac24';

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

HTTP/1.1 200 Ok

Update a Role's Project Scope

Use the special notation shown below to update a role with multiple new project scopes at once. For each ID, prefix with + to add or - to remove. Including neither will replace the list with the payload. It is not permitted to mix the two update methods at once.

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

{
  "scopes": {
    "project": ["+U2As9WsMthW5F5aeFECpCeDs"]
  }
}

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/roles/592d70418c5e3f2800408a74' \
  -d '{
    "scopes": {
      "projects": ["+U2As9WsMthW5F5aeFECpCeDs"]
    }
  }'

The role itself can be viewed with the scopes using the withScopes=true query parameter:

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

{
  "id": "592d70418c5e3f2800408a74",
  "version": 2,
  "type": "userInApp",
  "name": "Data Analyst",
  "description": "A role for all Brand Inspector Application Users",
  "scopes": {
    "projects": [
      "U2As9WsMthW5F5aeFECpCeDs"
    ]
  }
  "createdAt": 1496150081776,
  "updatedAt": 1496744121980
}

Set a Role's Scoped Roles

Use a PUT request to update a role with a list of IDs of roles that can access that role. For example, a Repair Engineer Supervisor role can be added by ID to the roles scopes of the Repair Engineer role to enable the supervisor to see and assign it.

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

{
  "scopes": {
    "roles": [ "596ccd9a1b0b282c00d5cfda" ]
  }
}

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

{
  "id": "592d70418c5e3f2800408a74",
  "version": 2,
  "type": "userInApp",
  "name": "Data Analyst",
  "description": "A role for all Brand Inspector Application Users in Europe.",
  "scopes": {
    "roles": [
      "596ccd9a1b0b282c00d5cfda"
    ],
    "projects": [
      "U2As9WsMthW5F5aeFECpCeDs"
    ]
  },
  "createdAt": 1500297818393,
  "updatedAt": 1500302769632
}

Read a Role's Scoped Roles

The roles that are visible to any given role are those that their current role is scoped to, i.e: those that include the current role in their scopes.roles field. The current user is determined using the Application User API Key authenticating the request.

GET /roles
Authorization: $APPLICATION_USER_API_KEY

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

[
  {
    "id": "596cba5a79fd982c00d25fda",
    "version": 2,
    "type": "userInApp",
    "name": "Data Analyst",
    "description": "A role for all Brand Inspector Application Users",
    "customFields": {},
    "createdAt": 1500297818393,
    "updatedAt": 1500302769632
  }
]

Read an Account's Role

Read the current role of an account, as well as other authentication information. The response contains a list of AccessDocument objects, each of which has a role field.

GET /accounts/:accountId/accesses
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://api.evrythng.com/accounts/UhpHrg39QCy9dsSddN8xhwnb/accesses'

const accountId = 'UhpHrg39QCy9dsSddN8xhwnb';

operator.sharedAccount(accountId).access()
  .read()
  .then(p => p[0])
  .then(access => console.log(access.role));

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

[
  {
    "id": "57bc4f351976e18a306f47b5",
    "account": "UhpHrg39QCy9dsSddN8xhwnb",
    "operator": "UhpMetUeBegbkUDpGgsk4hyq",
    "apiKey": "9O0Tqi92f78bGX376d1Nw4sfC49J78HcEqv1HLzDw...",
    "role": "admin"
  }
]

Set an Account's Role

Set the role of an account with a roleId. This replaces the previously assigned role. The AccessDocument should contain the roleId of the role to be assigned.

PUT /accounts/:accountId/accesses/:accessId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

AccessDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/accounts/UhpHrg39QCy9dsSddN8xhwnb/accesses/57bad69fc18104025b292da8' \
  -d '{
    "role": "5889cd38c4b3762e00667633"
  }'

const accountId = 'UhpHrg39QCy9dsSddN8xhwnb';
const accessId = '57bad69fc18104025b292da8';
const newRoleId = '58b0521a95cb272800a17a45';

const payload = { role: newRoleId };

operator.sharedAccount(accountId).access(accessId)
  .update(payload)
  .then(console.log);

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

{
  "id": "57bad69fc18104025b292da8",
  "account": "UhpHrg39QCy9dsSddN8xhwnb",
  "operator": "UEp4rDGsnpCAF6xABbys5Amc",
  "apiKey": "$OPERATOR_API_KEY",
  "role": "5889cd38c4b3762e00667633"
}

Application Default Role

When an application is created, it will contain a default role that Application Users in that application will be automatically assigned. The default application default role is the pre-defined "base_app_user" role. This allows Application Users to view all resources in that application's project. Custom Application User roles can be created to specify a different subset of permissions as required. See Role Permissions for more information.

If the application's defaultRole changes at some point in the future, all Application Users within that application will be assigned the new role automatically.

Set an Application's Default Role

PUT /projects/:projectId/applications/:applicationId
Content-Type: appplication/json
Authorization: $OPERATOR_API_KEY

{
  "defaultRole": "58f8773ffc7c042800fda32b"
}

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/projects/Uh5qRBqc4DcmbNbAANtMnrYm/applications/Uh6GfhFnmgScpnxwMsqmbbBk' \
  -d '{
    "defaultRole": "58f8773ffc7c042800fda32b"
  }'

const projectId = 'Uh5qRBqc4DcmbNbAANtMnrYm';
const applicationId = 'Uh6GfhFnmgScpnxwMsqmbbBk';
const defaultRoleId = '58f8773ffc7c042800fda32b';
const payload = { defaultRole: defaultRoleId };

operator.project(projectId).application(applicationId)
  .update(payload)
  .then(console.log);

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

{
  "id": "Uh6GfhFnmgScpnxwMsqmbbBk",
  "createdAt": 1480521204655,
  "customFields": {},
  "updatedAt": 1494509400307,
  "name": "Brand Inspector App",
  "project": "Uh5qRBqc4DcmbNbAANtMnrYm",
  "socialNetworks": {},
  "defaultRole": "58f8773ffc7c042800fda32b",
  "appApiKey": "8xolxjxxl64r7QeW5w..."
}