Users

This section contains all endpoints related to "users" of the MODE platform. Users are "end-users" of MODE projects.

Endpoints

The User object

  • idinteger

    This is a unique user ID assigned at time of creation.

  • projectIdinteger

    The project ID that this user belongs to.

  • creationTimestring| format is date-time

    The time when the user was created.

  • phoneNumberstring

    A valid phone number with country code (beginning with the '+' symbol). Present if project uses phone numbers to uniquely identify users.

  • emailstring

    A valid email address. Present if project uses email addresses to uniquely identify users.

  • externalKeystring

    If present, this is the unique key used in an external system to identify this user. This field is relevant only if project is using BYOU.

  • passwordstring

    A valid password. This is used only when creating or updating a user who logs in by email and password.

  • namestring

    Display name of the user.

  • verifiedboolean

    Displays true if the user has verified their account.

  • passwordUpdateTimestring| format is date-time

    The time when the password was last changed. Present only if user account is based on email/password.

  • auth2FActivatedboolean

    True if user has activated two-factor authentication.

The User object

{
    "id": 2076,
    "projectId": 1264,
    "creationTime": "2019-12-17T02:55:59.483Z",
    "email": "janedoe@tinkermode.com",
    "password": "secure_password",
    "name": "Jane Doe",
    "verified": false
}

The User Permission object

  • resourceTypestring| options are all, accessControlGroup, user, userLog, home, homeKeyValue, homeLog, homeDevice, homeSmartModuleREST, homeEvent, homeAlert, entityClass, entity, entityMetric, entityBlob, entityAlert, entityAlertRule, entityAssistant, entityAppProxy, entityCustomLog, alertRule, projectLog, projectAlert

    Resource type

  • actionsobject

    Resource IDs on which the user can perform actions. If the user has all objects access for the resource type, it contains “*” or “root” instead of listing all resource IDs.

Get all users

Endpoint
get /users
Description

Retrieves users of a project. Either projectId, readableByUserId, or accessControlGroupId is required. An optional search parameter may be provided. The search string may contain multiple phrases separated by whitespaces. When the search parameter is used, only users whose name, email address, phone number, or external key matching exactly or partially one of the phrases will be returned.

Query Parameters

  • projectId

    integer

    Return users of the specified project. The request must be made using the API the key of a user with permission to read all users, or a project API key with "Admin" privileges.

  • readableByUserId

    integer

    Return users that the specified user can read. The request must be made using the API the key of the specified user, or a project API key with "Admin" privileges.

  • accessControlGroupId

    integer

    If the caller uses this parameter with projectId or readableByUserIdFilter, filter result users by the the access control group. If the caller uses this parameter without projectId and readableByUserId, return users belonging to the access control group. The request must be made using the API the key of a user with permission to read users in the group, or a project API key with "Admin" privileges.

  • search

    string

    Search for users by keywords.

  • skip

    integer

    Number of users to skip over.

  • limit

    integer

    Maximum number of users to return.

    Default value is 25

    Minimum value is 1

Request Headers What's this?

  • Authorization

    required

    Must contain the API key of a user who has the permission to read all users of a project, or a Project API Key with admin permission.

Response
  • 200Successful retrieval of a list of users
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

[
  {
    "id": 1875,
    "projectId": 1264,
    "email": "janedoe@tinkermode.com",
    "verified": true,
    "name": "Jane Doe",
    "creationTime": "2019-10-07T21:35:27.874Z"
  },
  {
    "id": 2076,
    "projectId": 1264,
    "email": "johndoe@tinkermode.com",
    "verified": true,
    "name": "John Doe",
    "creationTime": "2019-12-17T02:55:59.483Z"
  }
]

Create a user

Endpoint
post /users
Description

When a project is created on MODE, developer must specify how user accounts should be handled. By default, a project uses the built-in user account system provided by MODE. But a project can also implement its own separate account system for its users. So based on the type of the project, this API call does one of the following.

Project Uses the Built-In Account System (Based on Phone Numbers)

Register a new user. The request body must be a valid user object containing the projectId, phoneNumber and name fields. The phone number must not be in use by a current user of the project. An SMS text containing a verification code will be sent to the user to confirm the registration. However, if request is made using an Admin User/Project API Key, the user is "pre-verified", and no confirmation text will be sent.

Project Uses the Built-In Account System (Based on Email Addresses)

If used for registering a new user, the request body must be a valid user object containing the projectId, email and name fields. In addition, a password field must also be present. The email address must not be in use by a current user of the project. An email message containing a verification URL will be sent to the user to confirm the registration. However, if request is made using an Admin User/Project API Key, only the projectId and email fields are required for the request. An invitation email will be sent to the user, and an "activation token" will be returned. The invitation email should contain an activation link for the user to activate their account, but in case the user has trouble receiving the email, the caller may share the link with them directly (contructed from the activation token returned).

Project is BYOU ("Bring-Your-Own-Users")

Create an entry in MODE that corresponds to an existing user in the project's own account system. The request object only needs to contain the projectId field. An optional externalKey field can be used to associate the user with an existing unique identifier. The request must also come with an Authorization header that contains a User/Project API Key with the permission to handle BYOU. The returned user object contains a unique user ID. The caller should store this user ID for future MODE API calls.

Request Headers What's this?

  • Authorization

    The API key of a user who has permission to create users, or a Project API Key with the BYOU or Admin permission is required, if the project is BYOU, or restricts user registration. Otherwise, anyone can register as a user and no Authorization header is need.

Request Body

  • projectId

    integer

    required

    The unique id for a project.

  • name

    string

    The name of the new user.

  • email

    string

    Email of the new user. Note Required if the project is configured to have email-based user accounts.

  • password

    string

    Password of the new user. Note Required if the project is configured to have email-based user accounts.

  • phoneNumber

    string

    Phone number of the new user. Note Required if the project is configured to have phone number-based user accounts.

  • externalKey

    string

    An existing unique identity associated with the new user. Note Optional and used only if project is configured to be BYOU.

  • accessControlGroupIds

    array

    Access Control Groups of the new user. Note This parameter is allowed only if the request is made by a user with permission to create users in the group, or a project API key with "Admin" privileges.

Response
  • 201Successfully created the user. The created object is returned in the response body. For an invited user, an "activation token" is also included in the returned object.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "projectId": 1264,
  "email": "jane@example.com",
  "name": "Jane Doe",
  "password": "a_secure_password"
}

Response Body Sample

{
  "id": 2076,
  "projectId": 1264,
  "email": "jane@example.com",
  "verified": true,
  "name": "Jane Doe",
  "creationTime": "2019-12-17T02:55:59.483Z"
}

Get a user

Endpoint
get /users/{userId}
Description

Retrieves the user with the specified ID.

Path Parameters

  • userId

    integer

    required

    The unique ID for the specified user.

Request Headers What's this?

  • Authorization

    required

    Must contain API key of the matching user, or the API key of a user with permissions to read other users, or a Project API Key with admin permission.

Response
  • 200Successfully retrieved a single user.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested user does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "id": 2389,
  "projectId": 1234,
  "phoneNumber": "+17149999999",
  "verified": true,
  "name": "Jane Doe",
  "creationTime": "2019-09-18T21:20:03.533Z"
}

Update a user

Endpoint
patch /users/{userId}
Description

This endpoint will update the user name and password with the specified ID. Only a project with "email" mode type can update a password.

Path Parameters

  • userId

    integer

    required

    The unique ID for the specified user.

Request Headers What's this?

  • Authorization

    required

    Must contain API key of the matching user, or the API key of a user with permissions to update other users, or a Project API Key with admin permission.

Request Body

  • password

    string

    A valid password. This is used only when creating or updating a user who logs in by email and password.

  • name

    string

    required

    Display name of the user.

Response
  • 204Successfully updated user's name or password. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404User was unable to be found. Please check the user ID.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "name": "Jane Smith",
  "password": "a_secure_password"
}

Delete a user

Endpoint
delete /users/{userId}
Description

Delete the user with the specified ID.

Path Parameters

  • userId

    integer

    required

    The unique ID for the specified user.

Request Headers What's this?

  • Authorization

    required

    Must contain API key of the matching user, or the API key of a user with permissions to delete other users, or a Project API Key with admin permission.

Response
  • 204Successfully deleted a single user. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404User was unable to be found. Please check the user ID.
  • 409The user cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get Log Entries

Endpoint
get /users/{userId}/logEntries
Description

Get debug and error log entries for user.

Path Parameters

  • userId

    integer

    required

    The unique ID for the specified user.

Query Parameters

  • begin

    string

    required

    Return entries bound by this timestamp. Format must conform to RFC3339.

  • end

    string

    required

    Return entries bound by this timestamp. Format must conform to RFC3339.

  • maxEntries

    integer

    Limit the number of entries returned.

Request Headers What's this?

  • Authorization

    required

    Must contain API key of the matching user, or the API key of a user with permissions to read user logs, or a Project API Key with admin permission.

Response
  • 200A list of logEntry objects are returned in the response body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get HTTP Access Log Entries

Endpoint
get /users/{userId}/httpLogEntries
Description

Get HTTP access log entries for user.

Path Parameters

  • userId

    integer

    required

    The unique ID for the specified user.

Query Parameters

  • begin

    string

    required

    Return entries bound by this timestamp. Format must conform to RFC3339.

  • end

    string

    required

    Return entries bound by this timestamp. Format must conform to RFC3339.

  • maxEntries

    integer

    Limit the number of entries returned.

Request Headers What's this?

  • Authorization

    required

    Must contain API key of the matching user, or the API key of a user with permissions to read user logs, or a Project API Key with admin permission.

Response
  • 200A list of httpLogEntry objects are returned in the response body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Change email address

Endpoint
post /users/{userId}/changeEmail
Description

Changes the email address of the user. An verification email will be sent to the new email address. The user account's email address will be updated when the recipient clicks the verification link in the email.

This API call is only allowed for projects with email address-based user accounts.

Path Parameters

  • userId

    integer

    required

    The unique ID for the specified user.

Request Headers What's this?

  • Authorization

    required

    Must contain API key of the matching user, or the API key of a user with permissions to create other users, or a Project API Key with admin permission.

Request Body

  • email

    string

    required

    The new email address to change to.

Response
  • 200Successfully sent a verification email to the new email address.

Request Body Sample

{
  "email": "new-email-user@tinkermode.com"
}

Response Body Sample

{
  "newEmail": "new-email-user@tinkermode.com"
}

Activate two-factor authentication

Endpoint
post /users/{userId}/activate2FA
Description

Complete the Two-Factor Authentication activation process. This endpoint is used after user has seeded an authenticator app with a TOTP secret obtained from the activate2FA/start endpoint.

Path Parameters

  • userId

    integer

    required

    The unique ID for the specified user.

Request Headers What's this?

  • Authorization

    required

    Must contain API key of the matching user.

Request Body

  • code

    string

    required

    A time-based one-time passcode (TOTP) obtained from an authenticator app seeded by the TOTP secret generated in the previous step of activation.

Response
  • 204User has successfully acivated 2FA.

Request Body Sample

{
  "code": "889301"
}

Start activating 2FA

Endpoint
post /users/{userId}/activate2FA/start
Description

To activate 2FA, a user must first obtain a time-based one-time passcode (TOTP) secret from this endpoint, and enter the secret into an authenticator app. Once the authenticator is seeded, the user should use the TOTP generated by the authenticator to complete the activation.

Path Parameters

  • userId

    integer

    required

    The unique ID for the specified user.

Request Headers What's this?

  • Authorization

    required

    Must contain API key of the matching user.

Request Body

  • password

    string

    required

    User's password.

Response
  • 200Activation process started. The returned object contains both the TOTP secret and a special `otpauth` URI. The URI embeds both the secret and other essential information about the TOTP. It is meant to be rendered as a QR code on a frontend application so that it can be easily conumed by an authenticator app.

Request Body Sample

{
  "password": "userpassword"
}

Deactivate two-factor authentication

Endpoint
post /users/{userId}/deactivate2FA
Description

Deactivate Two-Factor Authentication. The user must provide a correct password to carry out this action.

Path Parameters

  • userId

    integer

    required

    The unique ID for the specified user.

Request Headers What's this?

  • Authorization

    required

    Must contain API key of the matching user.

Request Body

  • password

    string

    required

    User's password.

Response
  • 204User has successfully deactivated 2FA.

Request Body Sample

{
  "password": "userpassword"
}

Get user permissions

Endpoint
get /users/{userId}/permissions
Description

Get permissions of the user.

Path Parameters

  • userId

    integer

    required

    The unique ID for the specified user.

Request Headers What's this?

  • Authorization

    required

    Must contain API key of the matching user, or the API key of a user with management permissions on the all resource type, or a Project API Key with admin permission.

Response
  • 200Successfully retrieved user permissions.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested permission does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.