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