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.

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
}

Get all users

Endpoint
get /users
Description

Retrieves all users of a project. 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

    required

    Return users of the specified project.

  • 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 a Project API Key with admin permission.

Response
  • 200Successful retrieval of a list of users

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 reqeuest is made using an Admin 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)

Register 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 Project API Key, the user is "pre-verified", and no confirmation email will be sent.)

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 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

    If project is BYOU, a Project API Key with the BYOU or Admin permission is required. Otherwise, an Admin Project API Key can be used to add a "pre-verified" user to system.

Request Body

  • projectId

    integer

    required

    The unique id for a project.

  • name

    string

    required

    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.

Response
  • 201Successfully created the user. The created object is returned in the response body.
  • 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": "janedoe@tinkermode.com",
  "name": "Jane Doe",
  "password": "a_secure_password"
}

Response Body Sample

{
  "id": 2076,
  "projectId": 1264,
  "email": "janedoe@tinkermode.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 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 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 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.

Change user email

Endpoint
post /users/{userId}/changeEmail
Description

Changes the email of the user. An email verification will be sent to the new email. Once verified, the user's email will be updated. Emails must be unique per project and project must be in email authentication mode.

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 a Project API Key with admin permission.

Request Body

  • email

    string

    required

    The new email address to change to.

Response
  • 200Successfully sent email verification to new email.

Request Body Sample

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

Response Body Sample

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