Managing Conditions

Operators who are allowed to manage other actors can add restrictions to other Operators. To manage restrictions, an admin Operator uses the Operator Access API and includes restrictions to an Operator's access.

For example, a factory admin with no restrictions gets all factories when listing places through the API:

GET /places

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

[
  {
    "id": "U8wQCBT7KXa4xHc5aCQk5pab",
    "createdAt": 1578062893343,
    "customFields": {},
    "tags": [],
    "updatedAt": 1578761145578,
    "name": "Cosmetique Active International (CAI)",
    "description": "Cosmétique Active International (CAI)",
    "position": {
      "type": "Point",
      "coordinates": [
        3.460977,
        46.181396
      ]
     },
    "address": {
      "street": "ZA LES ANCISES",
      "city": "Creuzier-le-Neuf",
      "country": "France",
      "countryCode": "FR"
    },
    "identifiers": {},
    "longitude": 3.460977,
    "latitude": 46.181396
  },
  {
    "id": "U8aQWUPTDBRWDmyCaBG5pwmp",
    "name": "Cosmétique Active Production (CAP)",
    "description": "Cosmétique Active Production (CAP)",
    "createdAt": 1578062818710,
    "customFields": {
      "type": "Factory"
    },
    "tags": [
      "Factory"
    ],
    "updatedAt": 1578761099372,
    "position": {
      "type": "Point",
      "coordinates": [
        3.412115,
        46.158034
      ]
    },
    "address": {
      "street": "28 rue de l'industrie",
      "postalCode": "03300",
      "city": "creuzier-le-vieux",
      "country": "France",
      "countryCode": "FR"
    },
    "identifiers": {
      "gs1:414": "3016050700019"
    },
    "longitude": 3.412115,
    "latitude": 46.158034
  }
]

To restrict a factory admin Operator to a specific factory, an account admin updates the operator access through the API and adds a restrictive condition to the conditions array in the form
factoryId:$ID_OF_THE_FACTORY:

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

{
  "conditions": [
    "factoryId:U8wQCBT7KXa4xHc5aCQk5pab"
  ]
}

When the factory admin tries to list all factories, they get only the ones listed in their conditions:

GET /places

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

[
  {
    "id": "U8wQCBT7KXa4xHc5aCQk5pab",
    "createdAt": 1578062893343,
    "customFields": {},
    "tags": [],
    "updatedAt": 1578761145578,
    "name": "Cosmetique Active International (CAI)",
    "description": "Cosmétique Active International (CAI)",
    "position": {
      "type": "Point",
      "coordinates": [
        3.460977,
        46.181396
      ]
     },
    "address": {
      "street": "ZA LES ANCISES",
      "city": "Creuzier-le-Neuf",
      "country": "France",
      "countryCode": "FR"
    },
    "identifiers": {},
    "longitude": 3.460977,
    "latitude": 46.181396
  }
]

📘
Condition on Factory ID
A condition on factoryId might have different meanings with different APIs. See the available restrictive conditions the platform currently supports, which APIs are affected by each condition, and how the APIs filter out those conditions.
For example, for an API key with factoryId conditions, the Places API only retrieves places for which the id matches the condition's factoryId.

See Operator Access to learn about restrictions the platform supports and their syntax.

Restriction inheritance

Restrictive conditions are inherited from the person who assigns them. This means that Operators can't create an access with permissions greater than their own.

When Operators who are restricted to a certain attribute value create or update other Operator accesses, their own restrictions must be applied to their subordinate Operators. If not, the Platform responds with an error.

For example, a factory admin has a restrictive condition on the Cosmetique Active International factory. This is their operator access payload:

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

When this factory admin invites another operator to their account through the API, the factory admin must include at least one of their own conditions. If they don't, the new Operator is not restricted at all and consequently has more access than the factory admin:

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

{
  "name": "OperatorName",
  "operator": "UP2tcQ4CdAnTDpVF2d4r9Gpf",
  "policies": [
    "$FACTORY_USER_ROLE_ID"
  ],
  "conditions": [],
  "identifiers": {},
  "tags": [],
  "customFields": {}
}

HTTP/1.1 400 Bad Request
Caller access exceeded. The following conditions must be present: factoryId:U8wQCBT7KXa4xHc5aCQk5pab

Conditions the caller doesn't already have are also blocked through the API:

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

{
  "name": "OperatorName",
  "operator": "UP2tcQ4CdAnTDpVF2d4r9Gpf",
  "policies": [
    "$FACTORY_USER_ROLE_ID"
  ],
  "conditions": [
    "factoryId:U8wQCBT7KXa4xHc5aCQk5pab",
    "factoryId:U8aQWUPTDBRWDmyCaBG5pwmp"
  ],
  "identifiers": {},
  "tags": [],
  "customFields": {}
}

HTTP/1.1 400 Bad Request
Caller access exceeded. Extra conditions cannot be provided: factoryId:U8aQWUPTDBRWDmyCaBG5pwmp

See Operator Access and Access Tokens for more detailed API examples.

📘Condition on Factory ID

Restriction inheritance

📘
Condition on Factory ID