ActivateAuthenticateAmplify
API Reference
DashboardSupportDeveloper Blog

Operators

A user in the EVRYTHNG platform is called an Operator. The Operator model stores basic user information such as name, email and date of birth.

The /operators API allows managing those user details, here users are able to create new operators or retrieve and update their own information.

❗️

Sensitive data

The /Operators API stores sensitive information about users, therefore it is only possible to retrieve or update (GET or PUT) operators by ID if the request API key matches the operator in question. In other words, you can only retrieve or update your own operator details.

Creating user accounts

Here's how you can create a new user account via the API:

  1. Ensure you're allowed to create operators, by making a call to the the /me API and confirming your permissions include operators:create.
  2. Create a new operator via the /Operators API, learn here how
  3. Invite the operator to your organisation account by creating a new operator access via the /OperatorAccess API, learn here how.

And voilà, the user has been added to your account.

Activate the user account

After following the steps above, your new operator has been added to your organisation account, however, the user account needs to be activated.
To do so, the user should go to the EVRYTHNG platform and try to login with their details.

The user will be prompted with an activation button that will send an email to the user's email address containing an activation link. By clicking this link, he or she will be forwarded to the EVRYTHNG platform where he or she will be able to login.

API Status
General Availability:
/operators
/operators/{operatorId}
/operators/{operatorEmail}

Jump To↓

OperatorDocument
Create an Operator
Get an Operator by ID
Get an Operator by Email
Update operator by ID

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

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

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

.email (string, read-only)
    The email address assigned to the operator user.

.password (string)
    The user's password. Must be of 8-64 characters length as 
    well as must contain at least 1 lowercase character, at 
    least 1 uppercase character, at least 1 digit and at least 1 
    special character.

.oldPassword (string)
    The user's password. Must be of 8-64 characters length as 
    well as must contain at least 1 lowercase character, at 
    least 1 uppercase character, at least 1 digit and at least 1 
    special character.

.firstName (string)
    The first name of the operator user.

.lastName (string)
    The last name of the operator user.

.birthday (BirthdayDocument)
    An Application User's birthday.

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

.photo (string)
    URL of the user's photo.

.gender (string, one of 'male', 'female')
    User's gender.

.loginAttempts (number, read-only)
    Number of wrong login attempts

.tfaEnabled (boolean)
    Flag indicating whether two-factor authentication is enabled

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object representing an Operator.",
  "properties": {
    "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
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    },
    "email": {
      "type": "string",
      "description": "The email address assigned to the operator user.",
      "readOnly": true
    },
    "password": {
      "type": "string",
      "description": "The user's password. Must be of 8-64 characters length as well as must contain at least 1 lowercase character, at least 1 uppercase character, at least 1 digit and at least 1 special character.",
      "minLength": 8,
      "maxLength": 64,
      "writeOnly": true
    },
    "oldPassword": {
      "type": "string",
      "description": "The user's password. Must be of 8-64 characters length as well as must contain at least 1 lowercase character, at least 1 uppercase character, at least 1 digit and at least 1 special character.",
      "minLength": 8,
      "maxLength": 64,
      "writeOnly": true
    },
    "firstName": {
      "type": "string",
      "description": "The first name of the operator user."
    },
    "lastName": {
      "type": "string",
      "description": "The last name of the operator user."
    },
    "birthday": {
      "additionalProperties": false,
      "type": "object",
      "description": "An Application User's birthday.",
      "required": ["day", "month", "year"],
      "properties": {
        "day": {
          "type": "integer",
          "description": "The day of the birthday.",
          "example": 1,
          "minimum": 1,
          "maximum": 31
        },
        "month": {
          "type": "integer",
          "description": "The month of the birthday.",
          "example": 12,
          "minimum": 1,
          "maximum": 12
        },
        "year": {
          "type": "integer",
          "description": "The year of the birthday.",
          "example": 2018,
          "minimum": 1900
        }
      }
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    },
    "photo": {
      "type": "string",
      "description": "URL of the user's photo."
    },
    "gender": {
      "type": "string",
      "description": "User's gender.",
      "enum": ["male", "female"]
    },
    "loginAttempts": {
      "type": "number",
      "description": "Number of wrong login attempts",
      "readOnly": true
    },
    "tfaEnabled": {
      "type": "boolean",
      "description": "Flag indicating whether two-factor authentication is enabled"
    }
  }
}

{
    "id": "UnaP5scsfcQ4tQwaRXEyheBd",
    "createdAt": 1606991929867,
    "customFields": {
        "subscribetonewsletter": true
    },
    "updatedAt": 1607011433682,
    "email": "[email protected]",
    "firstName": "Mike",
    "lastName": "Smith",
    "photo": "https://upload.wikimedia.org/wikipedia/commons/8/84/Example.svg",
    "birthday": {
        "day": 22,
        "month": 2,
        "year": 1990
    },
    "gender": "male",
    "loginAttempts": 0,
    "tfaEnabled": false
}

See also: BirthdayDocument

BirthdayDocument Data Model

.day (integer, required)
    The day of the birthday.

.month (integer, required)
    The month of the birthday.

.year (integer, required)
    The year of the birthday.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An Application User's birthday.",
  "required": ["day", "month", "year"],
  "properties": {
    "day": {
      "type": "integer",
      "description": "The day of the birthday.",
      "example": 1,
      "minimum": 1,
      "maximum": 31
    },
    "month": {
      "type": "integer",
      "description": "The month of the birthday.",
      "example": 12,
      "minimum": 1,
      "maximum": 12
    },
    "year": {
      "type": "integer",
      "description": "The year of the birthday.",
      "example": 2018,
      "minimum": 1900
    }
  }
}

Create an Operator

📘

Email, first name and last name are read-only fields

For security and traceability reasons you're not allowed to update your email or name via the API. Avoid creating operators with placeholder names as these will not be able to be changed via the API or the EVRYTHNG platform.

Create a new Operator.

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

OperatorDocument

curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://api.evrythng.io/v2/operators \
  -d '{
  "firstName": "Test first name",
  "lastName": "Test last name",
  "email": "Test email",
  "password": "Test password",
  "birthday": {
    "day": 1,
    "month": 1,
    "year": 2000
  },
  "gender": "male"
}'

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

{
  "id": "UFrPSfP3M9QBEsRaaXtEBAca,",
  "createdAt": 1609861380092,
  "updatedAt": 1609861380092,
  "email": "[email protected]",
  "firstName": "firstName",
  "lastName": "lastName",
  "birthday": {
    "day": 1,
    "month": 1,
    "year": 2000
  },
  "gender": "male",
  "operatorStatus": {
    "status": "inactive",
    "activationCode": "activationCode"
  },
  "loginAttempts": 0,
  "tfaEnabled": false
}

Read an Operator by id

The /operators API allows managing those user details, here users are able to create new operators or retrieve and update their own information.

❗️

Sensitive data

The /Operators API stores sensitive information about users, therefore it is only possible to retrieve or update (GET or PUT) operators by ID if the request API key matches the operator in question. In other words, you can only retrieve or update your own operator details.

Read a single operator.

GET /operators/:operatorId
Authorization: $OPERATOR_API_KEY

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

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

{
  "id": "UFrPSfP3M9QBEsRaaXtEBAca",
  "firstName": "firstName",
  "lastName": "lastName",
  "createdAt": 1490949609559,
  "updatedAt": 1490949609559,
  "email": "[email protected]",
  "loginAttempts": 0,
  "tfaEnabled": false
}

Read an Operator by email

The /operators API allows managing those user details, here users are able to create new operators or retrieve and update their own information.

❗️

Sensitive data

The /Operators API stores sensitive information about users, therefore it is only possible to retrieve or update (GET or PUT) operators by ID if the request API key matches the operator in question. In other words, you can only retrieve or update your own operator details.

Read a single operator.

GET /operators/:operatorEmail
Authorization: $OPERATOR_API_KEY

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

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

{
  "id": "UFrPSfP3M9QBEsRaaXtEBAca",
  "firstName": "firstName",
  "lastName": "lastName",
  "createdAt": 1490949609559,
  "updatedAt": 1490949609559,
  "email": "[email protected]",
  "loginAttempts": 0,
  "tfaEnabled": false
}

Update an operator

The /operators API allows managing those user details, here users are able to create new operators or retrieve and update their own information.

❗️

Sensitive data

The /Operators API stores sensitive information about users, therefore it is only possible to retrieve or update (GET or PUT) operators by ID if the request API key matches the operator in question. In other words, you can only retrieve or update your own operator details.

Update an Operator by ID.

📘

Email, first name and last name are read-only fields

For security and traceability reasons you're not allowed to update your email or name via the API. Please contact our service desk if you require to change either of these fields.

PUT /operators/:operatorId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

OperatorDocument (partial)

curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X PUT https://api.evrythng.io/v2/operators/:operatorId \
  -d '{
  "description": "Test updated description"
}'

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

{
  "id": "UFrPSfP3M9QBEsRaaXtEBAca",
  "firstName": "Mike",
  "lastName": "Smith",
  "createdAt": 1490949609559,
  "updatedAt": 1490949609559,
  "loginAttempts": 0,
  "tfaEnabled": false
}