Authenticate a user
POST/auth/user
Base URL: https://api.tinkermode.com
Description
Based on the type of the project, this API call does one of the following.
Project Uses the Built-In Account System (Based on Email Addresses)
Authenticate a user by password and return an API key. The request body must contain the email, appId and password parameters.
If user account has activated two-factor authentication, the returned object will contain
a token to be used in completing authentication process using the /auth/user/auth2F endpoint.
Project Uses the Built-In Account System (Based on Phone Numbers)
Exchange the auth code sent to user via SMS for an API key. The request body must contain the phoneNumber, appId and code parameters.
Project is BYOU ("Bring-Your-Own-Users")
Obtain an API key for a user. The request body must contain the projectId parameter, and either the userId or the externalKey parameter. The request must also come with an Authorization header that contains a Project API Key with the permission to handle BYOU.
Authentication
Send an Authorization header of the form ModeCloud <AUTH_CODE>.
Must contain a Project API Key with BYOU permission. Required for BYOU projects only.
Request body
Content type: application/x-www-form-urlencoded
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
appId | string | No | ID of the app being used to access the API. Required except for BYOU projects. | |
code | string | No | Auth code sent to user via SMS. Required only for projects with phone number-based user accounts. | |
email | string | No | Email address of user to be authenticated. Required only for projects with email address-based user accounts. | |
externalKey | string | No | External key associated with the user to be authenticated. Used only for BYOU projects. | |
password | string | No | Password of user to be authenticated. Required only for projects with email address-based user accounts. | |
phoneNumber | string | No | Phone number of user to be authenticated. Required only for projects with phone number-based user accounts. | |
projectId | integer | Yes | ID of project to which the user belongs. | |
userId | integer | No | ID of user to be authenticated. Used only for BYOU projects. |
Responses
200 User is successfully authenticated, or if the user has
activated two-factor authentication, user shall proceed to
finish authentication by using the token included in the returned object.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
auth2FToken | string | No | read-only (server-generated) | Token used for completing the two-factor authentication process. Token will expire within 3 minutes |
expirationTime | string | No | read-only (server-generated); format: date-time | This property is present if token has an expiration time. |
sudoer | string | No | read-only (server-generated) | This property is present if client is authenticated via sudo. |
token | string | No | read-only (server-generated) | Access token to be used in the HTTP Authorization header in future API requests. |
userId | integer | No | read-only (server-generated) | This property is present if token is associated with a user. |
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 invalid data or 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. |