Client Authentication
For handling API client authentication. These resources do not adhere strictly to a RESTful model.
Endpoints
The Authentication Info object
- type
Type of client entity, or 'nobody' if client is not authenticated.
- userIdinteger
This property is present if token is associated with a user.
- appIdstring
ID of app used. This property is present if token is associated with a user authenticated via an app.
- deviceIdinteger
This property is present if token is associated with a device.
- projectKeyNamestring
This property is present if token is assocaited with a project API key.
- projectIdinteger
This property is present if token is associated with a project.
- sudoerstring
This property is present if token is generated via sudo.
- expirationTimestring| format is date-time
This property is present if token has an expiration time.
The Authentication Info object
{
"type": "user",
"userId": 2081,
"appId": "controller_app",
"projectId": 1260
}
The Client Authentication object
- tokenstring
Access token to be used in the HTTP Authorization header in future API requests.
- userIdinteger
This property is present if token is associated with a user.
- expirationTimestring| format is date-time
This property is present if token has an expiration time.
- sudoerstring
This property is present if client is authenticated via sudo.
Get authentication state
Endpoint
get /auth
Description
The endpoint is used to retrieve the authentication state of an API Key. You may use this endpoint to confirm the corrent Authentication header has been set for Project, User or Device API Key. For those with "Sudo" ability, you may test the Sudo API key as well.
Request Headers What's this?
Authorization
required
Must contain a valid API key for Device, User or Project.
Response
- 200Successfully retrieve info about the identity of the client.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Response Body Sample
{
"type": "user",
"userId": 2081,
"appId": "controller_app",
"projectId": 1260
}
Authenticate a user
Endpoint
post /auth/user
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 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 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.
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.
Request Headers What's this?
Authorization
Must contain a Project API Key with BYOU permission. Required for BYOU projects only.
Request Body
projectId
integer
required
ID of project to which the user belongs.
appId
string
ID of the app being used to access the API.
Required except for BYOU projects.
phoneNumber
string
Phone number of user to be authenticated.
Required only for projects with phone number-based user accounts.
code
string
Auth code sent to user via SMS.
Required only for projects with phone number-based user accounts.
email
string
Email address of user to be authenticated.
Required only for projects with email address-based user accounts.
password
string
required
Password of user to be authenticated.
Required only for projects with email address-based user accounts.
userId
integer
ID of user to be authenticated.
Used only for BYOU projects.
externalKey
string
required
External key associated with the user to be authenticated.
Used only for BYOU projects.
Response
- 200User is successfully authenticated.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Initiate user auth with SMS
Endpoint
post /auth/user/sms
Description
Initiate the authentication process by triggering an SMS text to a user. The text contains an auth code for the user to exchange for an authentication token.
This API call is only allowed for projects with phone number-based user accounts.
Request Body
projectId
integer
required
ID of project to which the user belongs.
phoneNumber
string
required
Phone number of user to be authenticated. It needs to be registered already on MODE cloud by
Create User
API call.
Response
- 200SMS message successfully sent.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Request Body Sample
{
"projectId": 1260,
"phoneNumber": "+17149999999"
}
Response Body Sample
{
"recipient": "+17149999999"
}
Verify user email address
Endpoint
post /auth/user/emailVerification
Description
Verify a user account by an email verification token. The token can be found in the email sent after hitting the endpoint /auth/user/emailVerification/start listed below.
This API call is only allowed for projects with email address-based user accounts.
Request Body
token
string
required
Verification token emailed to user.
Response
- 200User's identity has been verified.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Request Body Sample
token=YWxpY2UrNDBAdGlua2VybW9kZS5jb218MTg3NHxMSEVJRlZPQkdBTFdTRVZRRkdIRg
Response Body Sample
{
"email": "janedoe@tinkermode.com",
"projectId": 1264
}
Initiate user email verification
Endpoint
post /auth/user/emailVerification/start
Description
Initiate the account verification process by sending out a verification email. For users who have lost the original message. This API call is only allowed for projects with email address-based user accounts.
Request Body
projectId
integer
required
ID of project to which the user belongs.
email
string
required
Email address of user.
Response
- 200An email has been sent to the specified email address.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Request Body Sample
{
"projectId": 1268,
"email": "janedoe@tinkermode.com"
}
Response Body Sample
{
"email": "janedoe@tinkermode.com"
}
Verify new user email
Endpoint
post /auth/user/newEmailVerification
Description
When a user changes their email, the user will be sent an verification email with a token to the new email. The user can verify their new email by submitting the token. This token can be found in the email after initiating the call to the endpoint /user/{userID}/changeEmail. This API call is only allowed for projects with email address-based user accounts.
Request Body
token
string
required
Activation token emailed to user.
Response
- 200Successfully verified user's new email and updated in the database.
- 401Authorization is required to access this resource.
- 403Invalid token.
- 500An unexpected error has occurred.
- 503Database error or email is already in use.
Request Body Sample
token=YWxpY2UrNDBAdGlua2VybW9kZS5jb218MTg3NHxMSEVJRlZPQkdBTFdTRVZRRkdIRg
Response Body Sample
{
"email": "janedoe@tinkermode.com",
"projectId": 1264
}
Activate user account
Endpoint
post /auth/user/activation
Description
When a new user is invited to a home, the user is originally in an inactive state. An email will be sent to the invited user with an activation token. The user can activate their account by submitting the account name and password along with the token.
This API call is only allowed for projects with email address-based user accounts.
Request Body
token
string
required
Activation token emailed to user.
name
string
required
User's name to be associated with the account.
password
string
required
Password for logging into the account.
Response
- 200User's account has be activated.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Request Body Sample
token= "MTI2NHxhbGljZStuZXdob21lQHRpbmtlcm1vZGUuY29tfFlMSE1aR0tRVFBWWFlCVUxTWU9Y&name=Jane+Doe&password=a_secure_password
Response Body Sample
{
"email": "janedoe@tinkermode.com",
"projectId": 1264
}
Reset user password
Endpoint
post /auth/user/passwordReset
Description
Reset the password of a user. The token can be found in the email initiated by the endpoint /auth/user/passwordReset/start
This API call is only allowed for projects with email address-based user accounts.
Request Body
token
string
required
Password reset token emailed to user.
newPassword
string
required
New password for user's account.
Response
- 200User's password has been updated.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Request Body Sample
token= "MTI2NHxhbGljZStuZXdob21lQHRpbmtlcm1vZGUuY29tfFlMSE1aR0tRVFBWWFlCVUxTWU9Y&name=Jane+Doe&newPassword=a_new_secure_password
Response Body Sample
{
"email": "janedoe@tinkermode.com",
"projectId": 1264
}
Initiate password reset for user
Endpoint
post /auth/user/passwordReset/start
Description
Initiate the password reset process by sending out an email containing a password reset token. For users who have forgotten their passwords.
This API call is only allowed for projects with email address-based user accounts.
Request Body
projectId
integer
required
ID of project to which the user belongs.
email
string
required
Email address of user.
Response
- 200An email has been sent to the specified email address.
- 401Authorization is required to access this resource.
- 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%40tinkermode.com
Response Body Sample
{
"email": "janedoe@tinkermode.com"
}
Authentication by sudo
Endpoint
post /auth/sudo
Description
A special endpoint for project administrator to assume the identity of a user to log into an app (a practice commonly known as "sudo"). This is useful for troubleshooting user issues. The caller must first obtain a sudo authorization token, usually from the project's "admin server". The User Session resulted from sudo will automatically expire after 30 minutes. This API call is not allowed for BYOU projects.
Request Body
token
string
required
Sudo authorization token.
Response
- 200Sudo access granted.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Initiate sudo authentication
Endpoint
post /auth/sudo/start
Description
Request a sudo authorization token for an authorized project administrator (the "sudoer"). This is usually done from some kind of "admin server" created for administrators to manage their applications or support their users. The returned token should be passed onto the sudoer immediately to complete the sudo process. This API call is not allowed for BYOU projects.
Request Headers What's this?
Authorization
required
Must contain a project API key with "Admin" privileges.
Request Body
sudoer
string
required
Identity of the administrator requesting sudo access.
targetUserId
integer
required
User ID of the sudo target.
targetAppId
string
required
ID of the app expected to be used to access the API.
Response
- 200Sudo authorization token issued and returned in the response body.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.