中文简体    English

IVYIOT Account Authorization Api


Version history:

Revision date version number Modified by desc
2019-12-14 V1.0 Yang Zhaoyan Documents published online

1.Introduction

WebService API: All requests return data in json format.

2.IVY Cloud Platform API General Example and Description

2.1 General examples

WebServiceAPI example:

  • https://{HOST}/gateway?service=controllerName.methodName?parm1=xxx&parm2=xxx

Note:

  • 1.HOST refers to the domain, and the sandbox environment domain is sandboxt-api.ivyiot.io;
  • 2.Service=controllerName.methodName, the interface name is specified here;
  • 3.The methods are mainly divided into GET and POST methods;

Returns the result:

{
    "errorCode":"",
    "failureDetails":"",
    "data":""/*if exist*/
}
  • a) errorCode is the error code. When an empty string is returned, it
    indicates success. For other values, refer to the corresponding API
    status code table.
  • b) failureDetails is the error description. When the
    error code is not empty, this field explains the meaning of the error
    code.
  • c) data: return data, when there is return data, the data is in
    this parameter, the specific data data structure see the specific Api
    interface

2.2 Api related configuration information

2.2.1 Api domain

Test environment:

  • sandboxt-api.ivyiot.io (overseas),
  • sandboxt-api.ivyiot.cn (China Mainland)

Online environment:

  • api.myfoscam.com(overseas)
  • api.myfoscam.cn (domestic)

2.2.2 Important parameters ( important )

Cloud platform internal application identity information

  • clientId: oemkey
  • clientSecret: 397ff5985bb7437198a9ef51b4815caf

User identity parameters (obtained through the password authorization
login interface)

  • openId: user identity Id
  • accessToken: user identity accessToken

2.3 Common Error Codes ( Important )

2.3.1 System error code

System-level error codes, all interface calls may throw such error
codes;

Code value desc Causes and solutions
FC_SERVICE_NOT_IMPLEMENT (009999) The api does not exist or is not implemented Check if the spelling of the api is correct
FC_INVALID_PARAMETER (000006) Request parameter error Whether the request parameters are complete, the parm is spelled correctly, and the http method is selected correctly (get or post)
FC_SYSTEM_ERROR (000099) system error Caused by server internal errors and service restart, check api calls or try again later

2.3.2 authentication error

The interface that needs to verify identity, the identity information is
incorrect or the identity information expires will throw the following
error

Code value desc Causes and solutions
FC_AUTH_APPKEY_NOT_EXISTS (030010) AppKey does not exist Check if the AppKey input is correct
FC_AUTH_APPSECRET_NOT_MATCH (030020) AppSecrect does not match Check if AppSecrect input is correct
FC_AUTH_OPENID_NOT_EXISTS (030030) openId does not exist Check if openId input is correct
FC_AUTH_TOKEN_NOT_EXISTS (030091) token does not exist Check if the input of openId and accessToken are correct
FC_AUTH_OPENID_NOT_MATCH (030031) openId does not match Check if openId input is correct
FC_AUTH_ACCESSTOKEN_NOT_MATCH (030040) accessToken does not match Check if accessToken is correct
FC_AUTH_ACCESSTOKEN_EXPIRED (030041) accessToken expired re-register

3.Foscam Cloud Platform API List

3.1 Account

3.1.1 Account Registration

Interface description:

  • Register an account

Request URL:

  • https://{HOST}/gateway?service=user.regist_v2

Request method:

  • POST

Request header:

name necessary type desc
Content-Type Yes String Content-Type: application / x-www-form-urlencoded

Request parameters:

parm type necessary desc length
username String required Account name (email) 50
password String required Account password, MD5 encrypted and then transmitted to the background (32-bit lowercase) 50
name String Optional username 64
address String Optional address 32
phoneNo String Optional contact number 20
country String required Country ( code in the result obtained by querying the registration country interface ) 10
language String required CHS / ENU 10
accessType String required User access method (1web, 2App) 1
oemCode String required Oem Vendor Number (Required) 20
appClientVersion String Optional Client version information 50
subscribeEdm int Optional Whether to subscribe to EDM mail, 1 subscription, 2 non-subscription 1
needActive int required The parameter value is fixed at 0, the account is automatically activated 1
isNewAppRegister int required Parameter value is fixed at 1 1

Return example:

{
    "errorCode":"",
    "failureDetails":""
}

Return parameter description:

parm desc
errorCode error type, see return code
failureDetails wrong description

Error code description:

Basic return code Description
FC_SERVICE_NOT_IMPLEMENT (009999) The api does not exist or is not implemented
FC_INVALID_PARAMETER (000006) Request parameter error
FC_SYSTEM_ERROR (000099) system error
Business return code Description
020012 username already exists
020081 User has activated
002501 Registration email failed

3.1.2 Query Registered Country

Interface description:

  • Query country list, used to fill in registration country parameters
    during registration

Request URL:

  • https://{HOST}/gateway?service=user.get_regist_country

Request method:

  • GET

Request header:

  • no

Request parameters:

  • no

Return example:

{
    "errorCode":"",
    "data":[
        {
            "code":"US",
            "enName":"America",
            "chName":"美国",
            "zone":"com",
            "area":"NA",
            "selectable":true
        },
        {
            "code":"AR",
            "enName":"Argentina",
            "chName":"阿根廷",
            "zone":"com",
            "area":"SA",
            "selectable":true
        },
        {
            "code":"VN",
            "enName":"Vietnam",
            "chName":"越南",
            "zone":"com",
            "area":"AS",
            "selectable":true
        }
    ]
}

Return parameter description:

parm desc
errorCode error type, see return code
failureDetails wrong description
data Return country object
data.code Country code, unique
data.enName Country English Name
data.chName Country Chinese Name
data.zone Country-owned subdivisions. Currently there are cn and com subdivisions.
data.selectable Indicate whether the country is available in this subdivision

Error code description:

Basic return code Description
FC_SERVICE_NOT_IMPLEMENT (009999) The api does not exist or is not implemented
FC_INVALID_PARAMETER (000006) Request parameter error
FC_SYSTEM_ERROR (000099) system error

3.1.3 Check if the account exists and has been activated

Interface description:

  • Check if the account exists and is activated

Request URL:

  • https://{HOST}/gateway?service=user.is_username_exists

Request method:

  • GET

Request header:

  • no

Request parameters:

parm type necessary desc length
username String required Account name (email) 50
oemCode String required Oem Vendor Number (Required) 20

Return example:

{
    "errorCode":"",
    "data":{
        "yes":true,
        "deviceNum":2,
        "country":"US"
    }
}

Return parameter description:

parm desc
errorCode error type, see return code
failureDetails wrong description
yes true, exists and activated; false, does not exist or exists and is not activated

Error code description: k

Basic return code Description
FC_SERVICE_NOT_IMPLEMENT (009999) The api does not exist or is not implemented
FC_INVALID_PARAMETER (000006) Request parameter error
FC_SYSTEM_ERROR (000099) system error

3.1.4 Change Password

Interface description:

  • User changes password

Request URL:

  • https://{HOST}/gateway?service=user.modify_password

Request method:

  • POST

Request header:

name necessary type desc
Content-Type Yes String Content-Type: application / x-www-form-urlencoded
Request parameters:
parm type necessary desc length
clientId String required appKey 40
openId String required openId (user logo) 40
accessToken String required accessToken 40
oldPassword String required Old password (value after md5) 50
newPassword String required New password (value after md5) 50

Return example:

{
    "errorCode":"",
    "failureDetails":""
}

Return parameter description:

parm Description

errorCode error type, see return code
failureDetails wrong description

Error code description:

Basic return code Description
FC_SERVICE_NOT_IMPLEMENT (009999) The api does not exist or is not implemented
FC_INVALID_PARAMETER (000006) Request parameter error
FC_SYSTEM_ERROR (000099) system error
Business return code Description
FC_AUTH_APPKEY_NOT_EXISTS (030010) appKey does not exist
FC_AUTH_APPSECRET_NOT_MATCH (030020) appSecrect does not match
FC_AUTH_OPENID_NOT_EXISTS (030030) openId does not exist
FC_AUTH_OPENID_NOT_MATCH (030031) openId does not match
FC_AUTH_ACCESSTOKEN_NOT_MATCH (030040) accessToken does not match
FC_AUTH_ACCESSTOKEN_EXPIRED (030041) accessToken expired

3.1.5 Forgot Password-Get Reset Code

Interface description:

  • User forgot password, send reset code to registration email

Request URL:

  • https://{HOST}/gateway?service=user.gen_resetpwd_code

Request method:

  • POST

Request header:

name necessary type desc
Content-Type Yes String Content-Type: application / x-www-form-urlencoded

Request parameters:

parm type necessary desc length
username String required Account name (email) 50
language String required CHS / ENU, Chinese or English 10
oemCode String required Oem Vendor Number 20

Return example:

{
    "errorCode":"",
    "failureDetails":""
}

Return parameter description:

parm Description

errorCode error type, see return code
failureDetails wrong description

Error code description:

Basic return code Description
FC_SERVICE_NOT_IMPLEMENT (009999) The api does not exist or is not implemented
FC_INVALID_PARAMETER (000006) Request parameter error
FC_SYSTEM_ERROR (000099) system error
Business return code Description
020010 username not exists
020080 user account has not be activated
002501 email send error

3.1.6 Forgot Password-Reset Password

Interface description:

  • Forgot Password-Account Reset Password

Request URL:

  • https://{HOST}/gateway?service=user.resetpwd

Request method:

  • POST

Request header:

name necessary type desc
Content-Type Yes String Content-Type: application / x-www-form-urlencoded

Request parameters:

parm type necessary desc length
username String required Account name (email) 50
resetPasswordCode String required Reset code 50
newPassword String required new password 50
oemCode String required Oem Vendor Number 20

Return example:

{
    "errorCode":"",
    "failureDetails":""
}

Return parameter description:

parm desc
errorCode error type, see return code
failureDetails wrong description

Error code description:

Basic return code Description
FC_SERVICE_NOT_IMPLEMENT (009999) The api does not exist or is not implemented
FC_INVALID_PARAMETER (000006) Request parameter error
FC_SYSTEM_ERROR (000099) system error
Business return code Description
FC_ACCOUNT_USERNAEM_NOT_EXISTS (020010) username not exists
FC_ACCOUNT_USER_RESET_PASSWORD_CODE_INVALID (020060) resetpwd code invalid
FC_ACCOUNT_NOT_ACTIVATED (020080) user account has not be activated
FC_ACCOUNT_USER_RESET_PASSWORD_CODE_WRONG_TOO_MANY_TIMES (020062) Too many times to enter the password reset code in one hour, please try again in one hour

3.1.7 Forgot Password-Query whether the reset code is valid

Interface description:

  • Forgot password-check whether the reset code is valid

Request URL:

  • https://{HOST}/gateway?service=user.is_resetpwd_code_valid

Request method:

  • GET

Request header:

  • no

Request parameters:

parm type necessary desc length
code String required Reset code 40
username String required Account name (email) 50
oemCode String required Oem Vendor Number (Required) 20

Return example:

{
    "errorCode":"",
    "data":{
        "yes":true
    }
}

Return parameter description:

parm desc
errorCode error type, see return code
failureDetails wrong description
yes is it effective
Error code description: k
Basic return code Description
FC_SERVICE_NOT_IMPLEMENT (009999) The api does not exist or is not implemented
FC_INVALID_PARAMETER (000006) Request parameter error
FC_SYSTEM_ERROR (000099) system error
Business return code Description
FC_ACCOUNT_USER_RESET_PASSWORD_CODE_WRONG_TOO_MANY_TIMES (020062) Too many times to enter the password reset code in one hour, please try again in one hour

3.1.8 Obtaining Account Information

Interface description:

  • Get account information

Request URL:

  • https://{HOST}/gateway?service=user.get_user_info

Request method:

  • GET

Request header:

  • no

Request parameters:

parm type necessary desc length
clientId String required appKey 40
openId String required openId (user logo) 40
accessToken String required accessToken 40

Return example:

{
    "errorCode":"",
    "data":{
        "id":111111,
        "username":"xxxxxx@xxx.com",
        "name":"xxxxxxxx",
        "nickname":"yyyyyyyy",
        "gender":2,
        "birthday":"1970-01-01",
        "phoneNo":"0755-8888888",
        "mobilePhoneNo":"13888888888",
        "country":"US",
        "ipCountry":"CN",
        "area":"NA",
        "ctime":1522567864000,
        "updateTime":1561021443000,
        "status":1,
        "type":0,
        "generalUserage":7,
        "otherUserage":"YYYYYY",
        "accessType":1,
        "betaStatus":1,
        "subscribeEdm":2
    }
}

Return parameter description:

parm desc
errorCode error type, see return code
failureDetails wrong description
data User object information
data.name username
data.address User address
data.phoneNo telephone number
data.mobilePhoneNo cellphone number
data.birthday birthday
data.gender 0: unknown, 1: male, 2: female
data.country country
data.province province
data.city city
data.ctime Creation time
data.updateTime Update time
data.status 0: Not activated 1 Activated
data.type 0: platform account, 1: qq, 2: weibo, 3: baidu, 101: facebook
data.generalUserage Bitwise or Store (homeSercurity, babyMonitor, PetMonitor, StoreSecurity, OfficeSecurity)
data.otherUserage
data.subscribeEdm 1 means subscribe, 2 means not subscribe

Error code description: k

Basic return code Description
FC_SERVICE_NOT_IMPLEMENT (009999) The api does not exist or is not implemented
FC_INVALID_PARAMETER (000006) Request parameter error
FC_SYSTEM_ERROR (000099) system error
Business return code Description
FC_AUTH_APPKEY_NOT_EXISTS (030010) appKey does not exist
FC_AUTH_APPSECRET_NOT_MATCH (030020) appSecrect does not match
FC_AUTH_OPENID_NOT_EXISTS (030030) openId does not exist
FC_AUTH_OPENID_NOT_MATCH (030031) openId does not match
FC_AUTH_ACCESSTOKEN_NOT_MATCH (030040) accessToken does not match
FC_AUTH_ACCESSTOKEN_EXPIRED (030041) accessToken expired

3.1.9 Modify user information

Interface description:

  • Modify user information

Request URL:

  • https://{HOST}/gateway?service=user.modify_user_info

Request method:

  • POST

Request header:

name necessary type desc
Content-Type Yes String Content-Type: application / x-www-form-urlencoded

Request parameters:

parm type necessary desc length
clientId String required appKey 40
openId String required openId (user logo) 40
accessToken String required accessToken 40
address String Optional Address (optional parameter) 50
phoneNo String Optional Contact number (optional parameter) 32
name String Optional Real name (optional parameter) 64
nickname String Optional Nickname (optional) 20
gender Int Optional 0: unknown, 1: male, 2: female (optional) 1
birthday String Optional (Optional parameter)
mobilePhoneNo String Optional (Optional parameter) 20
country String Optional (Optional parameter) 32
province String Optional (Optional parameter) 32
city String Optional (Optional parameter) 32

Return example:

{
    "errorCode":"",
    "failureDetails":""
}

Return parameter description:

parm desc
errorCode error type, see return code
failureDetails wrong description

Error code description:

Basic return code Description
FC_SERVICE_NOT_IMPLEMENT (009999) The api does not exist or is not implemented
FC_INVALID_PARAMETER (000006) Request parameter error
FC_SYSTEM_ERROR (000099) system error
Business return code Description
FC_AUTH_APPKEY_NOT_EXISTS (030010) appKey does not exist
FC_AUTH_APPSECRET_NOT_MATCH (030020) appSecrect does not match
FC_AUTH_OPENID_NOT_EXISTS (030030) openId does not exist
FC_AUTH_OPENID_NOT_MATCH (030031) openId does not match
FC_AUTH_ACCESSTOKEN_NOT_MATCH (030040) accessToken does not match
FC_AUTH_ACCESSTOKEN_EXPIRED (030041) accessToken expired
FC_AUTH_APPKEY_NOT_EXISTS (030010) appKey does not exist

3.2 Authorized Login

3.2.1 User Password Authorization (Login)

Interface description:

  • Sign in to get important identity information such as clientId and
    accessToken

Request URL:

  • https://{HOST}/gateway?service=oauth.authorize

Request method:

  • POST

Request header:

name necessary type desc
Content-Type Yes String Content-Type: application / x-www-form-urlencoded

Request parameters:

parm type necessary desc length
username String required username 50
password String required Password, encrypted using MD5 50
grantType String required Authorization: password 30
clientId String required Developer’s AppId 40
clientSecret String required Developer password 40
accessType int required User access method (1web, 2app) 1
oemCode String required Oem Vendor Number (Required) 20
updateToken int Optional This parameter is currently only used by alexa third-party logins, and the value is fixed at 1; other logins do not need to provide this parameter 1

Return example:

{
    "errorCode":"",
    "failureDetails":"",
    "data":{
        "openId":"",
        "accessToken":"",
        "refreshToken":"",
        "expiresIn":123456,
        "username":"username",
        "userId":111111,
        "country":"US",
        "betaStatus":1
    }
}

Return parameter description:

parm desc
errorCode error type, see return code
failureDetails wrong description
data Authorization information
data.openId OPENID (User Identity Identification)
data.accessToken Login token
data.refreshToken Refresh token
data.expiresIn Login token expiration time (unit: second)
data.usernmae username
data.betaStatus 0 / 1,0 is not a grayscale user, 1 is a grayscale user

Error code description:

Basic return code Description
FC_SERVICE_NOT_IMPLEMENT (009999) The api does not exist or is not implemented
FC_INVALID_PARAMETER (000006) Request parameter error
FC_SYSTEM_ERROR (000099) system error
Business return code Description
030010 appkey not exists
030020 appsecret not match appkey
030061 password not match
030080 user account has not be activated
020101 user account was registered in zone com
020102 user account was registered in zone cn

3.2.2 Authentication

Interface description:

  • Authentication identity information, required authentication
    identity parameters are obtained through the user password
    authorization interface

Request URL:

  • https://{HOST}/gateway?service=oauth.is_accesstoken_valid

Request method:

  • POST

Request header:

name necessary type desc
Content-Type Yes String Content-Type: application / x-www-form-urlencoded

Request parameters:

parm type necessary desc length
clientId String required appKey 40
openId String required openId (user logo) 40
accessToken String required accessToken 40

Return example:

{
    "errorCode":"",
    "failureDetails":"",
    "data":{
        "yes":true
    }
}

Return parameter description:

parm desc
errorCode error type, see return code
failureDetails wrong description

Error code description:

Basic return code Description
FC_SERVICE_NOT_IMPLEMENT (009999) The api does not exist or is not implemented
FC_INVALID_PARAMETER (000006) Request parameter error
FC_SYSTEM_ERROR (000099) system error
Business return code Description
030010 appkey not exists
030020 appsecret not match appkey
030030 openid not exists
030031 openid not match appkey
030040 accesstoken not match openid
030041 accesstoken expired
文档更新时间: 2020-06-30 19:59   作者：admin