Users

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

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.

  • 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

Retreives all users of a project. If the optional search parameters are used, users with matching name, email address or phone number will be returned. The search string is tokenized using whitespace and most punctuation as delimiters. Items matching at least one of the tokens will be returned. To search for exact phrases, wrap the search string in double-quotes ("). To exclude items matching a word, prepend a minus sign (-) to the word.

Authorization Headers What's this?

Must contain a Project API Key with admin permission.

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

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

Authorization Headers What's this?

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.

Body

  • projectId

    integer

    required

    The unique id for a project.

  • name

    string

    required

    The name of the new user.

  • password

    string

    Number of users to skip over. Note Required if the project is email type.

  • email

    string

    Email of the new user. Note Required if the project is email type.

  • phoneNumber

    string

    Phone number of the new user. Note Required if the project is phone type.

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.

Authorization Headers What's this?

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

URI Parameters

  • userId

    integer

    required

    The unique ID for the specified user.

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.

Authorization Headers What's this?

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

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.

URI Parameters

  • userId

    integer

    required

    The unique ID for the specified 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.

Authorization Headers What's this?

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

URI Parameters

  • userId

    integer

    required

    The unique ID for the specified user.

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.

Authorization Headers What's this?

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

Body

  • email

    string

    required

    The new email address to change to.

URI Parameters

  • userId

    integer

    required

    The unique ID for the specified user.

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