Client Authentication

For handling API client authentication. These resources do not adhere strictly to a RESTful model.

Endpoints

The Authentication Info object

  • type| options are user, device, project key, nobody

    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.