Get all users
GET/users
Base URL: https://api.tinkermode.com
Retrieves users of a project. Either projectId, readableByUserId, or accessControlGroupId is required. projectId and readableByUserId are mutually exclusive, and a request that combines them is rejected with a 400 INVALID_REQUEST response. accessControlGroupId may be used on its own or combined with projectId or readableByUserId to filter the result by the access control group. 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.
Authentication
Send an Authorization header of the form ModeCloud <AUTH_CODE>.
Must contain the API key of a user or service account who has the permission to read all users of a project, or a Project API Key with admin permission.
Query parameters
| Name | Type | Required | Constraints | Description |
|---|---|---|---|---|
accessControlGroupId | integer | No | If the caller uses this parameter with projectId or readableByUserId, filter result users by 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. | |
limit | integer | No | default: 25; min: 1 | Maximum number of users to return. |
projectId | integer | No | 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 | No | 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. | |
search | string | No | Search for users by keywords. | |
skip | integer | No | default: 0; min: 0 | Number of users to skip over. |
Responses
200 Successful retrieval of a list of users
Content type: application/json
A registered end-user of a project.
An array of objects with the following shape:
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
auth2FActivated | boolean | No | read-only (server-generated) | True if user has activated two-factor authentication. |
creationTime | string | No | read-only (server-generated); format: date-time | The time when the user was created. |
email | string | No | read-only (server-generated) | A valid email address. Present if project uses email addresses to uniquely identify users. |
externalKey | string | No | read-only (server-generated) | 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. |
id | integer | Yes | read-only (server-generated) | This is a unique user ID assigned at time of creation. |
managedExternally | boolean | No | read-only (server-generated) | True if user account is managed by an external ID provider such as Microsoft Entra ID. |
name | string | Yes | Display name of the user. | |
password | string | No | A valid password. This is used only when creating or updating a user who logs in by email and password. | |
passwordUpdateTime | string | No | read-only (server-generated); format: date-time | The time when the password was last changed. Present only if user account is based on email/password. |
phoneNumber | string | No | read-only (server-generated); pattern: ^(\+)([0-9]{5,})$ | A valid phone number with country code (beginning with the '+' symbol). Present if project uses phone numbers to uniquely identify users. |
projectId | integer | Yes | read-only (server-generated) | The project ID that this user belongs to. |
verified | boolean | No | read-only (server-generated) | Displays true if the user has verified their account. |
Response example
[
{
"creationTime": "2019-10-07T21:35:27.874Z",
"email": "janedoe@tinkermode.com",
"id": 1875,
"name": "Jane Doe",
"projectId": 1264,
"verified": true
},
{
"creationTime": "2019-12-17T02:55:59.483Z",
"email": "johndoe@tinkermode.com",
"id": 2076,
"name": "John Doe",
"projectId": 1264,
"verified": true
}
]401 Authorization is required to access this resource.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
403 Request failed because of denied permission.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
429 Request failed because of rate limit.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
500 An unexpected error has occurred.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
503 The service is temporarily unavailable.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |