Operator Access

The Operator Access API allows managing existing Operators for a given account. Here Operators with allowed roles are able to invite new Operators into their accounts, assign roles to them and apply attribute based restrictive conditions, so that they can only access data relevant to their context.

By creating Operator Accesses, one is adding Operators to a given account so that they can access resources on that account. Upon creation of operator accesses, their names, operator ID, access policies and restrictive conditions must be provided - this will qualify their access in the platform.

Assign Roles

An Operator allowed to manage other operator accesses can assign or remove access policies to their subordinates by making use of the API.

For example, a factory administrator Operator can assign the Factory User role to another Operator by:

PUT /accounts/:accountId/operatorAccess/:operatorAccessId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

{
  "policies": [
    "$FACTORY_USER_ROLE_ID"
  ]
}

In order to get a list of all available roles, Operators must use the Access Policies API .

Restrictive Conditions

Beyond access policies - that define what resources an Operator can access and the operations they can make on those resources - it is also possible to restrict access based on attribute filtering. Restrictive conditions are represented by the conditions field of an Operator Access payload. Jump to the API schema to find more about the syntax.

A certain sourcing manager that is responsible for 10 different factories may only need access to data that is relevant to those factories. Moreover, factory administrators may only need access to data that is produced on their factory.
This level of restrictive conditions can be achieved by adding conditions to the Operator Access document through this API.

Read about Restrictive Conditions to understand the concept and common use case examples.

Restrictive Conditions on Operator Access API

The Operator Access API supports restrictive conditions on an access policy ID. Meaning that for a given API key with a restrictive condition on accessPolicyId the API will only allow this API key to manage actors whose assigned access policies are present on the caller's restrictive conditions.

Getting "my own" current access

To retrieve their own access details for a given account, operators can reach the /me API using their access API key. This is available for almost all roles for any Operators with a valid API key and will return the current Operator access details, including their restrictions and detailed roles.

Dashboards and Apps that need to make operations on behalf of Operators can adjust feature restrictions based on the caller's access retrieved through this endpoint.

API Status
General Availability:
/accounts/{accountId}/operatorAccess/{operatorAccessId}
/accounts/{accountId}/operatorAccess
/me

Jump To↓

OperatorAccessDocument
Create an Operator Access
Get an account Operator access
Read all Operator Accesses
Update operator access by ID
Delete an Operator Access

OperatorAccessDocument Data Model

An object representing an operator access.

.name (string, required)
    The name of the operator.

.description (string)
    The description of the operator access.

.operator (string, required)
    The operator ID

.policies (array of string, max. 100, required)
    An array of policy IDs

.conditions (array of string, max. 256, required)
    A conditions array.

.tags (array of string)
    Array of string tags associated with this resource.

.identifiers (IdentifiersDocument)
    Various identifiers (EPC, GTIN, etc.) as a JSON object with 
    one or more key-value pairs.

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

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object representing an operator access.",
  "readOnly": true,
  "required": ["name", "email", "conditions", "policies"],
  "properties": {
    "name": {
      "description": "The name of the operator.",
      "type": "string",
      "example": "Operator access for [email protected]",
      "minLength": 5,
      "maxLength": 128
    },
    "description": {
      "description": "The description of the operator access.",
      "type": "string",
      "maxLength": 256
    },
    "operator": {
      "description": "The operator ID",
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The operator ID.",
          "readonly": true
        },
        "name": {
          "type": "string",
          "description": "The name of the operator.",
          "readonly": true
        },
        "email": {
          "type": "string",
          "description": "The email of the operator.",
          "readonly": true
        }
      }
    },
    "policies": {
      "description": "An array of policy IDs",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 24,
        "maxLength": 24
      },
      "uniqueItems": true,
      "maxItems": 100
    },
    "conditions": {
      "description": "A conditions array.",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9_-]+:[A-Za-z0-9_-]+$"
      },
      "maxItems": 256,
      "uniqueItems": true
    },
    "tags": {
      "type": "array",
      "description": "Array of string tags associated with this resource.",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "identifiers": {
      "type": "object",
      "description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    },
    "x-filterable-fields": [{
      "name": "email",
      "type": "string",
      "operators": ["="]
    }, {
      "name": "policies",
      "type": "list of string",
      "operators": ["="]
    }, {
      "name": "conditions",
      "type": "list of string",
      "operators": ["="]
    }]
  }
}

{
  "id": "UsFQTQPFKG7UHraab3wE3Fhb",
  "name": "Operator Name",
  "description": "A description",  
  "operator": "UP2tcQ4CdAnTDpVF2d4r9Gpf",
  "policies": [
    "UPb7Eq8hwpktcaaabfahfpdq"
  ],
  "conditions": [
    "factoryId:U8wQCBT7KXa4xHc5aCQk5pab"
  ],
  "identifiers": {},
  "tags": [],
  "customFields": {},
  "createdAt": 1586442216863,
  "updatedAt": 1586442216863
}

Create an Operator Access

Creates an operator access for account

POST /accounts/:accountId/operatorAccess
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

OperatorAccessDocument

curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://api.evrythng.io/v2/accounts/:accountId/operatorAccess \
  -d '{
  "email": "[email protected]",
  "policies": [
    "UPb7Eq8hwpktcaaabfahfpdq"
  ],
  "conditions": [
    "factoryId:UPBCycCpgVGArgYc5y5UnkAg"
  ]
}'

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

{
  "id": "UsFQTQPFKG7UHraab3wE3Fhb",
  "operator": "UJWCycEbgATDrgYc5y5UnkTe",
  "email": "[email protected]",
  "description": "Access for a factory administrator",
  "policies": [
    "UPb7Eq8hwpktcaaabfahfpdq"
  ],
  "conditions": [
    "factoryId:UPBCycCpgVGArgYc5y5UnkAg"
  ]
}

Get an account Operator access

Reads and returns account operator access by ID

GET /accounts/:accountId/operatorAccess/:operatorAccessId
Authorization: $OPERATOR_API_KEY

curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://api.evrythng.io/v2/accounts/:accountId/operatorAccess/:operatorAccessId

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

{
  "id": "UsFQTQPFKG7UHraab3wE3Fhb",
  "name": "First Last",
  "operator": "UJWCycEbgATDrgYc5y5UnkTe",
  "email": "[email protected]",
  "description": "Access for a factory administrator",
  "policies": [
    "UPb7Eq8hwpktcaaabfahfpdq"
  ],
  "conditions": [
    "factoryId:UPBCycCpgVGArgYc5y5UnkAg"
  ]
}

Read all Operator Accesses

Read all operator access for given account

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

curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://api.evrythng.io/v2/accounts/:accountId/operatorAccess

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

[
  {
    "id": "UsFQTQPFKG7UHraab3wE3Fhb",
    "name": "First Last",
    "operator": "UJWCycEbgATDrgYc5y5UnkTe",
    "email": "[email protected]",
    "description": "Access for a factory administrator",
    "policies": [
      "UPb7Eq8hwpktcaaabfahfpdq"
    ],
    "conditions": [
      "factoryId:UPBCycCpgVGArgYc5y5UnkAg"
    ]
  },
  {
    "id": "UsFQTQPFKG7UHraab3wE3Fhb",
    "name": "[email protected]",
    "operator": "UJWCycEbgATDrgYc5y5UnkTe",
    "description": "Access for a factory administrator",
    "policies": [
      "UPb7Eq8hwpktcaaabfahfpdq"
    ],
    "conditions": [
      "factoryId:UPBCycCpgVGArgYc5y5UnkAg"
    ]
  }
]

Update operator access by ID

Updates and returns operator access by ID

PUT /accounts/:accountId/operatorAccess/:operatorAccessId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

OperatorAccessDocument (partial)

curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X PUT https://api.evrythng.io/v2/accounts/:accountId/operatorAccess/:operatorAccessId \
  -d '{
  "description": "A description",
  "policies": [
    "123456789012345678901234"
  ],
  "conditions": [
    "factoryId:123932QJ1235823412S741WG4'"
  ]
}'

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

{
  "id": "Ud6TycDekE5afp6M8QAEEMhp",
  "operator": "UJWCycEbgATDrgYc5y5UnkTe",
  "name": "first last",
  "email": "[email protected]",
  "name": "[email protected]",
  "description": "Factory admin",
  "policies": [
    "123456789012345678901234"
  ],
  "conditions": [
    "places:123932QJ1235823412S741WG4'"
  ]
}

Delete an Operator Access

Deletes an account operator access by ID

DELETE /accounts/:accountId/operatorAccess/:operatorAccessId
Authorization: $OPERATOR_API_KEY

curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X DELETE https://api.evrythng.io/v2/accounts/:accountId/operatorAccess/:operatorAccessId

HTTP/1.1 204 No Content

Get the caller's own account Operator access and inline policies

Reads and returns account operator access and inline policies based on the caller's API key.

GET /me
Authorization: $OPERATOR_API_KEY

curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://api.evrythng.io/v2/me

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

{
  "id": "Ud6TycDekE5afp6M8QAEEMhp",
  "operator": "123932QJ1235823412S741WG4",
  "name": "first last",
  "email": "[email protected]",
  "description": "access description",
  "policies": [
    {
      "name": "FactoryAdministratorPolicy",
      "description": "Description of FactoryAdministratorPolicy",
      "permissions": [
        "actions:create",
        "places:list,read,update",
        "operatorAccess:list,read,update",
        "products:list,read",
        "purchaseOrders:list,read",
        "thngs:read"
      ],
      "uiPermissions": [
        "activation",
        "authenticate"
      ],
      "homepage": "authenticate",
      "identifiers": {
        "ean": "aen232032"
      },
      "tags": [
        "roles",
        "and",
        "permissions"
      ]
    },
    {
      "name": "BrandProtector",
      "permissions": [
        "actions:create",
        "products:list,read",
        "purchaseOrders:list,read",
        "thngs:read"
      ],
      "uiPermissions": [
        "brandProtection",
        "authenticate"
      ],
      "homepage": "brandProtection"
    }
  ],
  "conditions": [
    "places:UPBCycCpgVGArgYc5y5UnkAg"
  ]
}