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.
- auth2FTokenstring
Token used for completing the two-factor authentication process. Token will expire within 3 minutes
- 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 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 authenticaiton 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.
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, or if the user has activated two-factor authentication, user shall proceed to finish authentication by using the token included in the returned object.
- 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.
Complete two-factor authentication
Endpoint
post /auth/user/auth2F
Description
For a user who has activated two-factor authentication, they must complete their authentication by providing a time-based one-time passcode (TOTP) from their authenticator, along with the token obtained in the previous authentication step (supplying an email and a password) If the TOTP is incorrect, the client may retry with the same token, until the token's expiration (3 minutes from issuance).
Request Body
code
string
required
Time-based one-time passcode from an authenticator application.
auth2FToken
string
required
Token obtained from the previous step of authentication.
Response
- 200User is successfully authenticated and an API token is issued.
- 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
code=889200&auth2FToken=XXXXXXXXXXXXXXXX
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"
}
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"
}
Complete authentication by OpenID Connect
Endpoint
post /auth/user/oidc
Description
If a project has added alternative user authentication methods that support OpenID Connect, its frontend app should use this set of endpoints to handle the authentication flow. This endpoint is for completing the process when a user has been redirected back from an Identity Provider after they have consented to share information with MODE. The frontend app should extract the state and code from the URL and call this endpoint to validate the code and obtain a client authentication token.
Request Body
projectId
integer
required
ID of project to which the user belongs.
methodId
string
required
ID of the project's User Authentication Method that is being used.
code
string
required
Authorization code embedded in the URL redirected from the Identity Provider after the user has consented to share information with MODE.
redirectUrl
string
required
The same redirect URL that was used to obtain the authorization URL. It is needed by the Identity Provider to verify the authorization code.
appId
string
required
ID of the app the user is using.
Response
- 200User has been 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.
Request Body Sample
{
"projectId": 1260,
"methodId": "google",
"code": "XXXXXXX",
"redirectUrl": "https://example.com/sign_in",
"appId": "webapp"
}
Initiate authentication by OpenID Connect
Endpoint
post /auth/user/oidc/start
Description
For a user to sign in via OpenID Connect, the frontend app should use this endpoint to retrive the URL to redirect the user to, so that they can authorize an Identity Provider to share their information with MODE.
Response
- 200The authorization URL has been returned.
- 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,
"methodId": "google",
"redirectUrl": "https://example.com/sign_in",
"state": "SOME_OPAQUE_STRING"
}
Response Body Sample
{
"authUrl": "https://example.com/auth?state=XXXXX&clientId=YYYYYY"
}
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.