Part 3. Cloud API: APP Service APIs

Account Endpoints

Click an ▶ API endpoint to expand/collapse its content.
POST/accounts/registration
Purpose: Registers a user account via a Example Service Provider.
Notes
When successful, the user owns a unique account. The user is able to:
  • Add and edit Device and Device Group information.
  • Add other general users to this user account.
  • Set the permissions for viewing devices.
A mobile phone number is required when the user creates the account.
  • The user's phone number must not be duplicated.
  • When the registration succeeds, the system will send a set of verification code to the registered phone and the user must enter the code within the time limit.
  • When the verification succeeds, the account is formally activated.
  • Any promotion and system notifications are sent to the user's email.
Request Method
POST
Changelog
Aug 21, 2017 First version
Oct 11, 2017 Second version
Dec 21, 2017 Third version
Permission
Must verify that the app_id and app_key of the Header exists and its correctness to continually register the user account in this App.
Request Parameters
Need Parameter Type Description
Required user_name String User account to be registered.
  • The characters must not be more than 50.
  • User name must not contain certain characters.
  • These invalid characters are ^ @ , & = * ' "
    • Caret (^)
    • At sign (@)
    • Comma (,)
    • Ampersand (&)
    • Equals (=)
    • Asterisk (*)
    • Quote (")
    • Single quote (')
Optional user_email String User email address to be registered.
Required country_code String The country code.
Required user_mobile String User mobile phone number to be registered.
Required user_password String User password to be registered.
  • Password characters must be 8 to 36.
  • The password must include uppercase, lowercase, numeric, and special characters.
Return Values (JSON)
Fields Type Description
account_id String The unique account_id generated after the registration.
account_created_time String The time of account registration completed, by using Timestamp (UTC).
Sample Response
Sample response when a request has succeeded: 
{
  "account_id": "6b094d38-a2a9-454d-bf77-2a9823f9c074",
  "account_created_time": "1500617357"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 SAME_USER_MOBILE The user_mobile already exists.

▲ Top

PUT/accounts/:account_id
Purpose: Edits the username, email address, password, or mobile phone number of the account.
Notes
When the phone number is updated, it has to be verified once again.
If the verification fails, the user will not be allowed to edit the new phone number.
Request Method
PUT
APIs Type
Administrative Functions for Account and Permissions Management.
Changelog
Sep 28, 2017 First version
Oct 11, 2017 Second version
Dec 21, 2017 Third version
Permission
Must verify that the app_id and app_key of the Header belong to the App to continually take further actions.
Request Parameters
Need Parameter Type Description
Required user_name String Username to be updated.
Optional user_email String User email address to be updated.
Required user_mobile String User’s mobile phone number to be updated.
Return Values (JSON)
Fields Type Description
account_id String The user's account_ID.
account_updated_time String The time when the account ID is updated by using Timestamp (UTC).
Sample Response
Sample response when a request has succeeded: 
{
  "account_id": "6b094d38-a2a9-454d-bf77-2a9823f9c074",
  "account_updated_time": "1500617357"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 SAME_USER_MOBILE Same user_mobile already exists.

▲ Top

POST/accounts/verifycode
Purpose: Sends the verification code when the user forgets the password or adds new users.
Notes
This API can be called when the user forgets or would like to add new users.
  • Example Service Provider will verify whether the mobile phone exists in the App.
  • If it exists, the system will send a set of verification code to the user.
When a new user is added, the Example Service Provider will verify whether the mobile phone exists.
  • If the mobile phone number is duplicated, the user has to re-enter a new number until the phone number is new and valid.
  • The system will then send a set of verification code to the user.
  • When the code is submitted and verified, the user can take the further actions.
Request Method
POST
Changelog
Oct 11, 2017 First version
Dec 21, 2017 Second version
Permission
Must verify that the app_id and app_key of the Header belong to the App to continually send the verification code.
Request Parameters
Need Parameter Type Description
Required verify_type Integer Get the verification code by actions:
  • 1 = User registration
  • 2 = Forgot password
Required country_code String The country code.
Required user_mobile String User’s mobile phone number to be verified.
Return Values (JSON)
Fields Type Description
verify_expired_time String The time when the verification code is sent by using Timestamp (UTC).
Sample Response
Sample response when a request has succeeded: 
{
  "verify_expired_time": 1500617357
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_USER_MOBILE The entered mobile phone number does not exist.

▲ Top

PUT/accounts/verifycode
Purpose: Verifies the correctness of the verification code.
Notes
When the user enters the verification code, the API is called to verify the correctness.
  • When successful, the system will take the further actions, including forgetting the password or registering a new account.
  • Must verify the account to get the verification code that belongs to the App.
Request Method
PUT
Changelog
Oct 11, 2017 First version
Dec 21, 2017 Second version
Permission
Must verify that the app_id and app_key of the Header belong to the App to continually update account status.
Request Parameters
Need Parameter Type Description
Required user_mobile String The user's mobile phone number.
Required verify_code String The verification code to be entered.
Return Values (JSON)
Fields Type Description
user_mobile String The user's mobile phone number.
verify_status Integer Whether the verification is successful:
  • 0 = Failed
  • 1 = Successful
Sample Response
Sample response when a request has succeeded: 
{
  "user_mobile":"0912345678",
  "verify_status": 1
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 VERIFY_CODE_TIMEOUT When the verification code expires, must generate a new set of code.
400 INVALID_VERIFY_CODE If the verification code is invalid or does not exist, must generate a new set of code.

▲ Top

POST/accounts/status
Purpose: Activates or deactivates the user account.
Notes
When the account is deactivated, all users belonging to this account are not allowed to take any actions.
Must verify the activated/deactivated account belongs to the App.
Request Method
POST
Changelog
Aug 21, 2017 First version
Oct 11, 2017 Second version
Dec 21, 2017. Third version
Permission
Must verify that the app_id and app_key of the Header belong to the App to continually update account status.
Request Parameters
Need Parameter Type Description
Required account_id String The account to be updated (account_id).
Required account_status Integer The user account to be activated or deactivated:
  • 0 = Deactivated
  • 1 = Activated
Return Values (JSON)
Fields Type Description
account_updated_time String The time when the account_id is updated, by using Timestamp (UTC).
Sample Response
Sample response when a request has succeeded: 
{
  "account_updated_time": "1500617357"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 VALUE_ERROR_INVALID_VALUE The account_id does not exist.

▲ Top

PUT/accounts/:account_id/reset-password
Purpose: The user who resets the password must confirm the old password's correctness.
Notes
If correct, the user can reset the password.
  • If not, the user is not allowed to reset the password.
  • Must verify the user account of the user taking this action belongs to the App and passes the verification to continually reset the password.
Request Method
PUT
Changelog
Nov, 10. 2017 First version
Dec 21, 2017 Second version
Permission
Must verify that the app_id and app_key of the Header belong to the App to continually update account status.
Request Parameters
The characters must be at least 8 to 36.
Need Parameter Type Description
Required account_id String The user to reset the password.
Required old_password String The old password.
Requirednew_password String New password to be reset.
  • The password must include uppercase, lowercase, numeric, and special characters.
Return Values (JSON)
Fields Type Description
account_updated_time String The time when the user information is updated, by using Timestamp (UTC).
Sample Response
Sample response when a request has succeeded: 
{
  "account_updated_time": "1500617357"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID account_id does not exis.
400 OLD_PASSWORD_FAILED Old password is not correct

▲ Top

PUT/accounts/forgotpassword
Purpose: This API endpoint is called when the user forgets the login password.
Notes
The user's mobile phone number must be verified successfully to change the password.
The user account must be activated.
Request Method
PUT
Changelog
Nov, 10. 2017 First version
Dec 21, 2017 Second version
Permission
Must verify that the app_id and app_key of the Header belong to the App to continually update account status.
Request Parameters
Need Parameter Type Description
Required user_mobile String The user’s mobile phone number.
Required verify_code String The verification code to be entered.
Required new_password String New password to be reset.
  • The characters must be at least 8 to 36.
  • The password must contain uppercase, lowercase, numeric and special characters.
Return Values (JSON)
Fields Type Description
account_updated_time String The time when the user information is updated, by using Timestamp (UTC).
Sample Response
Sample response when a request has succeeded: 
{
  "account_updated_time": "1500617357"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID account_id does not exist.
400 INVALID_USER_MOBILE The user’s mobile phone number does not exist.

▲ Top

POST/accounts/login/local
Purpose: The user logs in by using the registered account and password.
Notes
Besides entering the correct account and password, the user account must be activated.
Must verify the user account belongs to the App.
Request Method
POST
Changelog
Aug 21, 2017 First version
Oct 11, 2017 Second version
Dec 21, 2017 Third version
Permission
Must verify that the app_id and app_key of the Header belong to the App to continually update account status.
Request Parameters
Need Parameter Type Description
Required user_mobile String User's mobile phone to be logged in.
Required user_password String User's password to be logged in.
Return Values (JSON)
Fields Type Description
account_id String The unique value of each account_id.
account_token String The token when the login is successful.
token_expired_time String The expiration time after the login by using Timestamp (UTC).
user_info Object User information of the login account.
  • user_email: User’s email address. If no, it will be an empty string.
  • user_mobile: User’s mobile phone number. if no, it will be an empty string
  • user_name: Username
Sample Response
Sample response when a request has succeeded: 
{
  "account_id": "6b094d38-a2a9-454d-bf77-2a9823f9c074",
  "account_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ
    9.eyJlbWFpbCI6ImVsZWFub3JfbGFpQHdpc3Ryb24uY29tIiwid
    XNlclR5cGUiOjEsImxvZ2luVHlwZSI6ImxvY2FsIiwidXVpZCI6
    OTcsImRldmljZUlEIjoid2ViIiwianRpIjoiODYwYjczYWItM2Q
    yZi00ZDgyLWJlYjUtNDliYmUzZmViY2NkIiwiaWF0IjoxNDk5Nz
    M4NTk5LCJleHAiOjE1MDIzMzA1OTl9.dLotcSjMLyxfw-n-fvaE
    pGV1zlnJL7spJFthMiTC6iY",
  "token_expired_time": "1501138920",
  "user_info": {
    "user_email": "nice@ wistron.com",
    "user_mobile": "0919111111",
    "user_name": "nice"
  }
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_USER_MOBILE The user's mobile phone number does not exist.
400 ERROR_PASSWORD_OR_USER_MOBILE The user's phone number or password is incorrect.
400 ACCOUNT_STATUS_DISABLE The account has not been activated yet.

▲ Top

PUT/accounts/login/other
Purpose: The user logs in with third party account. For example, Facebook or WeChat.
Notes
If the user logs in by using third part account for the first time, the third party account and user information will be simultaneously registered to the App.
API Service Management must verify the validation of access token from the third party, which must be authentic access token to log in to Example service.
Request Method
PUT
Changelog
Aug 21, 2017 First version
Oct 11, 2017 Second version
Dec 21, 2017 Third version
Permission
Must verify that the app_id and app_key of the Header exists and that they are correct.
Request Parameters
Need Parameter Type Description
Required account_type String The type of third party account logged in by the user, for example, Facebook.
Required access_token String Access token obtained from the third party after logging in by using third party account.
Optional others various data types Provide other parameters if required based on different ways to log in by using third part account.
  • The information will be enough to verify when using the third party account.
Return Values (JSON)
Fields Type Description
account_id String The unique identification of each account_id.
account_type String The type of the user.
  • local = registered with mobile phone number.
  • Facebook = registered with Facebook account.
account_token String The token after the user logs in.
account_expired_time String The expiration time of the token after the login, by using Timestamp (UTC).
user_info Object User information of the login account.
  • user_email: User’s email address. If no, it will be an empty string.
  • user_mobile: User’s mobile phone number. If no, it will be an empty string.
  • user_name: Username.
Sample Response
Sample response when a request has succeeded: 
{
  "account_id": "6b094d38-a2a9-454d-bf77-2a9823f9c074",
  "account_type": "wechat",
  "account_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
    eyJlbWFpbCI6ImVsZWFub3JfbGFpQHdpc3Ryb24uY29tIiwidXN
    lclR5cGUiOjEsImxvZ2luVHlwZSI6ImxvY2FsIiwidXVpZCI6OT
    csImRldmljZUlEIjoid2ViIiwianRpIjoiODYwYjczYWItM2QyZ
    i00ZDgyLWJlYjUtNDliYmUzZmViY2NkIiwiaWF0IjoxNDk5NzM4
    NTk5LCJleHAiOjE1MDIzMzA1OTl9.dLotcSjMLyxfw-n-fvaEpG
    V1zlnJL7spJFthMiTC6iY",
  "account_expired_time": 1501138920,
  "user_info": {
    "user_email": "nice@wistron.com",
    "user_mobile": "0919111111",
    "user_name": "nice"
  }
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 THIRD_LOGIN_SAME_USER_MOBILE The user_mobile already exists.

▲ Top

GET/accounts/:account_id/token/:account_token
Purpose: When the user adds a new user, the user must edit the new user’s information.
Notes
When finished, a QR code will be generated for the new user to scan to join.
The API token only allows 90 seconds for the user to log in.
  • The token will expire in 90 seconds.
  • "90 seconds" is one of the suggested options.
  • The time can be modified.
Request Method
GET
Changelog
Oct 11, 2017
Permission
Must verify that the app_id and app_key of the Header belong to the App to continually take further actions.
Request Parameters
Need Parameter Type Description
Required account_id String The user's account_id.
Required account_token String The user's token.
Return Values (JSON)
Fields Type Description
user_name String The use's username.
account_id String The user's account_id.
user_mobile String The user's mobile phone number.
Sample Response
Sample response when a request has succeeded: 
{
  "account_id": "6b094d38-a2a9-454d-bf77-2a9823f9c074",
  "user_mobile": "0919111111",
  "user_name": "nice"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID account_id does not exist.

▲ Top

GET/accounts/app/:app_id
Purpose: Gets the list of accounts of the App.
Notes
Each account is related to its Main User with Main User information included.
Must verify the received list of account belongs to the App.
Request Method
GET
Changelog
Aug 21, 2017
Permission
Must verify whether the app_id and app_key of the Header belong to the App (compared with app_id of Path) to continually get the account list.
Request Parameters
Need Parameter Type Description
Required app_id String The list of the account of which App.
Return Values (JSON)
Fields Type Description
app_id String Get the ID number of the App that the account belongs to.
accounts Array Get the array of the account list.
Note: If no account is returned, it will return an empty array [].
Elements contained in accounts array:
Fields Type Description
account_id String The unique value of each account: account_id.
account_status Integer Account status:
  • 0 = Deactivated
  • 1 = Activated
account_created_time String The time when the account is registered by using Timestamp (UTC).
main_user Object Main user information of the account registration:
  • user_id: unique value of User ID
  • user_email: User's email address. If no, it will display as empty string.
  • user_mobile: User's mobile phone number. If no, it will display as empty string.
  • user_name: Username.
  • user_type: User type:
    • Local = register with email address or mobile phone.
    • Facebook = register with Facebook account.
Sample Response
Sample response when a request has succeeded: 
{
  "app_id": "6b094d38-a2a9-454d-bf77-2a9823f9c074",
  "accounts": [{
    "account_id": "6b094d38-a2a9-454d-bf77-2a9823f9c074",
    "account_status": 1,
    "account_created_time": "1500617357",
    "main_user": {
      "user_id": "c92be72d-40fc-462f-ae52-9e997e514277",
      "user_email": "nice@wistron.com",
      "user_mobile": "0919111111",
      "user_name": "nice",
      "user_type": "local"
    }
  }]
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 VALUE_NOT_MATCH app_id and the app_id of the header do not match.

▲ Top

GET/accounts/authorize?client_id={client_id}&scope={scope}&response_type={response_type}&redirect_uri={redirect_uri}&state={state}
Purpose: This URL request is used to start the sign-in process with the code flow.
Request Method
GET
Changelog
Dec 21, 2017
Permission
None.
Request Parameters
Need Parameter Type Description
Required client_id String The assigned app_id.
Required scope String A space-separated list of scopes that the app requires.
Required response_type String The type of response expected from the authorization flow. For this flow, the value must be code.
Required redirect_uri String The redirect URL that the browser is sent to when authentication is completed.
Required state String This can be any state of information to preserve across the OAuth process. For example, a token to prevent CSRF attacks.
Return Values (JSON)
None.
Sample Response
Upon successful authentication and authorization of the application, the web browser will be redirected to your redirect URL with additional parameters added to the URL. 
redirect_uri?code=df6aa589-1080-b241-b410-c4dff65dbf7c&state=12345
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_REDIRECT_URI redirect_id does not exist.
400 INVALID_SCOPE scope does not exist.
400 INVALID_RESPONSE_TYPE response_type is not code. Must be code.

▲ Top

POST/accounts/authorize
Purpose: After you have received the code value, you can redeem this code for a set of tokens that allow you to authenticate with the API.
Request Method
POST
Changelog
Dec 21, 2017
Permission
None.
Request Parameters
Need Parameter Type Description
Required client_id String The assigned app_id.
Required client_secret String The assigned app_key.
Required redirect_uri String The redirect URL that the browser is sent to when authentication is completed. This should match the redirect_uri in the first request.
Required code String The received authorization code in the first authentication request.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
token_type String The type of authentication. The type must be "Bearer".
expires_in Integer The time that the access token is valid (in seconds).
scope String A space-separated list of scopes that your app requires.
access_token String The requested access token.
  • The app can use this token to authenticate to the secured resource, such as a web API.
refresh_token String An OAuth 2.0 refresh token.
  • The app can use this token to obtain additional access tokens after the current access token expires.
  • Refresh tokens are long-lived, and can be used to retain access to resources for extended periods of time.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 123,
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "nice-cloud-api",
  "access_token": "EwCo...AA==",
  "refresh_token": "eyJh...9323",
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_REDIRECT_URI account_id does not exist.
400 INVALID_CODE code does not exist.

▲ Top

POST/accounts/refresh-token
Purpose: Gets a new access token, refreshes a token, extends the access token.
Notes
The access token obtained after login has an expiration.
  • To avoid the user from being logged out when it expires, this API is able to determine the requirement, (for example, when the user is still taking actions) to extend the access token.
  • The prerequisite to extend the access token is that the token is still valid.
Request Method
POST
Changelog
Dec 21, 2017
Permission
None.
Request Parameters
Need Parameter Type Description
Required client_id String The assigned app_id.
Required client_secret String The assigned app_key.
Required redirect_uri String The redirect URL that the browser is sent to when authentication is complete.
  • This should match the redirect_uri in the first request.
Required refresh_token String The refresh token you previously received.
Required grant_type String Must be "refresh_token".
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
token_type String The type of authenticatio
  • The type must be "Bearer".
expires_in Integer The time that the access token is valid (in seconds).
scope String A space-separated list of scopes that your app requires.
access_token String The requested access token.
  • The app can use this token to authenticate the secured resource, such as a web API.
refresh_token String An OAuth 2.0 refresh token.
  • The app can use this token to obtain additional access tokens after the current access token expires.
  • Refresh tokens are long-lived, and can be used to retain access to resources for extended periods of time.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 123,
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "nice-cloud-api",
  "access_token": "EwCo...AA==",
  "refresh_token": "eyJh...9323",
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_REDIRECT_URI redirect_id does not exist.
400 INVALID_REFRESH_TOKEN refresh_token does not exist.
400 INVALID_GRANT_TYPE grant_type does not exist.

▲ Top

GET/accounts/logout?client_id={client_id}&redirect_uri={redirect_uri}
Purpose: Deletes the token when the user logs out, and invalidates the token obtained when logged in.
Notes
Must verify the user account belongs to the App.
Request Method
GET
Changelog
Dec 21, 2017
Permission
None.
Request Parameters
Need Parameter Type Description
Required client_id String The assigned app_id.
Required redirect_uri String The redirect URL that the browser is sent to when authentication is complete.
  • This should match the redirect_uri in the first request.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 123
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_REDIRECT_URI redirect_id does not exist.

▲ Top

POST/accounts/password-strength
Purpose: Examine and test the password strength.
Notes
The password must have "strong" strength.
The suggested password policies are:
  • Password must be between 8 to 36 characters long.
  • Password must contain an uppercase, lowercase, numeric and symbol characters.
Request Method
POST
Changelog
Dec 21, 2017
Permission
None.
Request Parameters
Need Parameter Type Description
Required password String The password to be entered.
  • Password must be between 8 to 36 characters long.
  • Must contain an uppercase, lowercase, numeric and symbol characters.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond)
password_result Integer Verify the password strength to be "strong":
  • 0: Valid
  • 1: Invalid
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 123,
  "password_result": 1
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 PASSWORD_IS_NOT_SUITABLE The entered password is invalid.

▲ Top