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

NameTypeRequiredConstraintsDescription
accessControlGroupIdintegerNoIf 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.
limitintegerNodefault: 25; min: 1Maximum number of users to return.
projectIdintegerNoReturn 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.
readableByUserIdintegerNoReturn 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.
searchstringNoSearch for users by keywords.
skipintegerNodefault: 0; min: 0Number 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:

PropertyTypeRequiredConstraintsDescription
auth2FActivatedbooleanNoread-only (server-generated)True if user has activated two-factor authentication.
creationTimestringNoread-only (server-generated); format: date-timeThe time when the user was created.
emailstringNoread-only (server-generated)A valid email address. Present if project uses email addresses to uniquely identify users.
externalKeystringNoread-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.
idintegerYesread-only (server-generated)This is a unique user ID assigned at time of creation.
managedExternallybooleanNoread-only (server-generated)True if user account is managed by an external ID provider such as Microsoft Entra ID.
namestringYesDisplay name of the user.
passwordstringNoA valid password. This is used only when creating or updating a user who logs in by email and password.
passwordUpdateTimestringNoread-only (server-generated); format: date-timeThe time when the password was last changed. Present only if user account is based on email/password.
phoneNumberstringNoread-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.
projectIdintegerYesread-only (server-generated)The project ID that this user belongs to.
verifiedbooleanNoread-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

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.

403 Request failed because of denied permission.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.

429 Request failed because of rate limit.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.

500 An unexpected error has occurred.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.

503 The service is temporarily unavailable.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.