授权管理¶

用户可以将设备通过授权分享给其他用户控制，可以分享所有权限也可以只分享IFTTT或预约功能或某个控制指令，被授权的用户也可以看到设备的历史统计信息等。除此之外还可以指定授权失效时间，过期自动解除授权。

正向授权¶

正向授权指设备属主主动地将设备分享给其他用户，属主需要知道其他用户uid。

授权者通过扫码获取被授权者的用户UID

st=>start: 授权者通过扫码获取被授权者的用户UID
op1=>operation: 授权者调用正向授权接口:>#正向授权
e=>end: 完成授权，流程结束

st->op1->e

POST https://user-openapi.hekr.me/authorization HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

{
  "ctrlKey": [
      "89f089..."
  ],
  "grantee": "3399...",
  "expireAt": 1503479651538,
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "results": [
        {
            "ctrlKey": "89f089...",
            "result": "success"
        }
    ],
    "success": 1,
    "failure": 0
}

请求体¶

参数	是否必须	含义
ctrlKey	true	授权设备的ctrlKey列表
grantee	true	被授权用户uid
expireAt	false	过期时间(UNIX毫秒时间戳), 空表示永不过期

返回体¶

字段	含义
results.ctrlKey	对应请求体中设备的ctrlKey
result	授权结果 success 表示成功; 失败的原因可能有 permission deny (用户无权授权设备), exceed share limit (设备授权分享达到上限, 比如10个) grantee not exists (授权用户不存在)
success	设备授权成功的个数
failure	设备授权失败的个数

反向授权¶

所谓反向授权，典型场景即设备属主选取设备生成分享的链接或者二维码发放出去，被授权者们可以直接扫二维码请求授权，倘若属主的用户偏好中_ReverseAuthAgree值设置为true，那么该授权者可以不经过同意直接获取这个设备的操作权，否则 Hekr Cloud 会发给属主一个含有被授权者请求属主授权该设备的推送消息，属主可以同意或拒绝该请求，如若同意则创建了一个授权关系。

st=>start: 授权者选择要授权的设备并生成二维码共享:>#创建授权链接二维码
scan=>operation: 被授权者扫描二维码:>#申请设备授权
no_audit=>condition: 授权者是否允许反向授权直接通过
auth_limit_check=>condition: 设备授权数是否达到上限
auth_ret_limit_fail=>end: 授权失败，推送被授权者结果:>../推送消息/#申请失败
auth_ret_deny_fail=>end: 授权失败，推送被授权者结果:>../推送消息#申请被拒绝

auth_apply_push=>operation: 授权者受到授权申请推送:>../推送消息#申请用户扫描授权码属主收到推送
auth_apply_audit=>condition: 授权者是否同意:>#同意授权申请
auth_apply_success=>end: 授权成功, 推送给被授权者:>../推送消息/#申请成功

st->scan->no_audit
no_audit(yes)->auth_limit_check
no_audit(no, right)->auth_apply_push->auth_apply_audit

auth_limit_check(yes)->auth_apply_success
auth_limit_check(no, right)->auth_ret_limit_fail

auth_apply_audit(yes)->auth_limit_check
auth_apply_audit(no, bottom)->auth_ret_deny_fail

创建授权链接(二维码)¶

随后您的应用将收到的 reverseAuthorizationTemplateId 转换成链接或二维码的方式分享出去，随即被授权者根据得到的reverseAuthorizationTemplateId调用申请设备授权。

POST https://user-openapi.hekr.me/authorization/reverse/authUrl HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

{
  "ctrlKey": [
      "89f089..."
  ],
  "expireAt": 1503479651538,
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "reverseAuthorizationTemplateId": "16c89273f43c4483b00e09fdf8d659a8"
}

请求体¶

参数	是否必须	含义
ctrlKey	true	授权设备的ctrlKey
expireAt	false	过期时间(UNIX毫秒时间戳), 空表示永不过期

返回体¶

参数	含义
reverseAuthorizationTemplateId	临时授权码(1小时后过期)

申请设备授权¶

POST https://user-openapi.hekr.me/authorization/reverse/register?reverseTemplateId={reverseTemplateId} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

请求参数¶

参数	是否必须	含义
reverseTemplateId	true	创建授权链接(二维码)得到的授权码

如果属主允许直接授权(用户偏好中_ReverseAuthAgree 为true)，申请授权后用户直接获得设备访问权，授权流程结束。否则属主会收到推送。

查看授权申请记录¶

Note

指定reverseRegisterId 时仅会返回1条记录或0条(授权申请记录已过期)。

GET https://user-openapi.hekr.me/authorization/reverse/register?reverseRegisterId={reverseRegisterId} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
    {
        "registerId": "8bb3946a4acd409f9f0a33029663efa8:33995635439",
        "grantor": "33995635438",
        "grantee": "33995635439",
        "ctrlKeyList": [
            "89f0894dcf9049e086c68e4f26b9d0d3",
            "a36bd458df03444fbf5f1f10d4d50a75"
        ],
        "ctrlKey": "89f0894dcf9049e086c68e4f26b9d0d3",
        "expireAt": 32503654800000,
        "longCreateTime": 1503513598020,
        "deviceName": "中文产品名称,ff",
        "devTid": null,
        "granteeName": "kj",
        "granteeAvater": {
            "small": "https://stage-allinone-ufile.hekr.me/user-file/e605fa1e-c017-4995-8533-23e181fae022/1503400309282.png"
        }
    }
]

请求参数¶

参数	是否必须	含义
reverseRegisterId	false	授权申请记录ID 来自用户申请扫描授权码属主收到推送

返回体¶

参数	含义
registerId	授权申请记录ID
grantor	属主
grantee	申请授权的用户
ctrlKeyList	被授权的设备ctrlKey列表
ctrlKey	已废弃请使用ctrlKeyList
devTid	已废弃设备devTid
expireAt	过期时间(UNIX毫秒时间戳) 空表示永久授权
longCreateTime	授权申请时间(UNIX毫秒时间戳)
deviceName	设备名称(多个时使用","隔开)
granteeAvater	申请授权用户的头像

属主获取到授权申请记录后调用同意授权申请或拒绝授权申请。

同意授权申请¶

POST https://user-openapi.hekr.me/authorization/reverse?reverseRegisterId={registerId} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

请求参数¶

参数	是否必须	含义
registerId	true	授权申请记录ID 来自用户申请扫描授权码属主收到推送

属主同意后会尝试进行授权动作，因设备授权超过上限或设备已解绑可能导致授权失败，申请授权用户会收到反向授权申请结果推送。

拒绝授权申请¶

DELETE https://user-openapi.hekr.me/authorization/reverse/register/{registerId} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

参数	是否必须	含义
registerId	true	授权申请记录ID 来自用户申请扫描授权码属主收到推送

拒绝后申请授权用户会收到申请被拒绝推送。

列举设备授权¶

GET https://user-openapi.hekr.me/v1/device-auth/{ctrlKey} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "owner": {
        "uid": "40440378120",
        "name": "40440378120"
    },
    "authUsers": [{
        "uid": "30441278120",
        "name": "twoyao",
        "grantAt": 1511408768052,
        "expireAt": 1511408768052
    }]
}

返回体¶

字段	含义
owner.uid	设备属主的用户ID
owner.name	设备属主的名字
authUsers.uid	被授权者用户ID
authUsers.name	被授权者名字
authUsers.grantAt	授权时间(UNIX毫秒时间戳)
authUsers.grantAt	授权过期时间(UNIX毫秒时间戳)

列举设备授权(废弃)¶

设备用户调用该接口查看授权设备的授权信息，属主可以看到所有的授权记录，被授权用户只能看到自己的授权记录。

GET https://user-openapi.hekr.me/authorization?ctrlKey=${ctrlKey} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
    {
        "grantee": "33995635439",
        "grantTime": 1503479761945,
        "expire": 32503654800000,
        "subDevTids": ["03871..."],
        "grantorName": "foo 明明",
        "granteeName": "kj"
    }
]

请求参数¶

参数	是否必须	含义
ctrlKey	true	设备ctrlKey

返回体¶

字段	含义
grantorName	属主名称
grantee	被授权用户
granteeName	被授权用户名称
grantTime	授权时间(UNIX毫秒时间戳)
expire	授权过期时间
subDevTids	子设备ID 可能为null

编辑授权¶

属主调用, 请求参数、返回体同正向授权。

PUT https://user-openapi.hekr.me/authorization HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

{
  "ctrlKey": [
      "89f089..."
  ],
  "grantee": "3399...",
  "expireAt": 1503479651538,
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "results": [
        {
            "ctrlKey": "89f089...",
            "result": "success"
        }
    ],
    "success": 1,
    "failure": 0
}

取消授权(废弃)¶

属主可以取消所有用户的授权，被授权用户只能取消自己的授权。

DELETE https://user-openapi.hekr.me/authorization?devTid={devTid}&ctrlKey={ctrlKey}&grantee={grantee}&randomToken=${randomToken} HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

参数	是否必须	含义
devTid	true	设备devTid
ctrlKey	true	设备ctrlKey
grantee	true	需要取消的被授权用户, 多个用户以","隔开，如果为空表示取消所有用户的授权关系
randomToken	false	第一次调用有场景或IFTTT时返回，确认删除后第二次调用传入

当被授权用户在该设备上有场景或IFTTT时, 返回:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "randomKey": "zkj...",
    "scenes": [
        {
            "sceneId": "abc..",
            "sceneName" : "下班回家",
            "uid": "2308..."
        }
    ],
    "ifttts": [
        {
            "ruleId": "abc..",
            "ruleName": "联动规则",
            "uid": "2308..."
        }
    ]
}

字段	含义
randomKey	用于确认删除第二次调用以randomToken传入
scenes	该授权用户创建的场景
ifttts	改授权用户创建的IFTTT规则

当被授权用户在该设备上没有有场景或IFTTT时, 直接接触授权并放回:

HTTP/1.1 204 OK
Content-Type: application/json;charset=UTF-8

取消授权¶

属主可以取消所有用户的授权，被授权用户只能取消自己的授权。

DELETE https://user-openapi.hekr.me/v1/device-auth/{ctrlKey}?grantee={grantee} HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

HTTP/1.1 204 OK
Content-Type: application/json;charset=UTF-8

参数	是否必须	含义
ctrlKey	true	设备ctrlKey
grantee	true	需要取消的被授权用户, 多个用户以","隔开

查询授权记录¶

属主调用，查询我的设备授权给其他用户的记录。

GET https://user-openapi.hekr.me/authorization/history?ctrlKey={ctrlKey}&passAuth={passAuth} HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "content": [
        {
            "registerId": "599be67004c29401d6536d47",
            "longCreateTime": 1503389296261,
            "result": true,
            "granteeName": "kj",
            "deviceName": "中文产品名称",
            "ctrlKey": "89f089...",
            "ctrlKeyList": [
                "89f089..."
            ],
            "message": "您已经将设备[中文产品名称]授权给kj. "
        }
    ],
    "last": false,
    "totalElements": 40,
    "totalPages": 40,
    "first": true,
    "numberOfElements": 1,
    "sort": [
        {
            "direction": "ASC",
            "property": "longCreateTime,DESC",
            "ignoreCase": false,
            "nullHandling": "NATIVE",
            "ascending": true
        }
    ],
    "size": 1,
    "number": 0
}

请求参数¶

参数	是否必须	含义
ctrlKey	false	过滤参数设备ctrlKey
passAuth	false	当该值为true时，仅返回授权成功的记录

返回体¶

字段	含义
registerId	授权记录ID
message	授权记录描述信息
deviceName	设备名称多个设备以","分隔
granteeName	被授权人名称
result	授权结果仅当所有设备都授权成功时为true 否则false
longCreateTime	授权时间(UNIX毫秒时间戳)
ctrlKeyList	授权设备列表
ctrlKey	已废弃授权设备列表中第一个设备

错误码表¶

错误码	提示信息	中文释义	可能造成的原因
5200000, 620000	Success	成功	无
5400000	Error	未知错误	该行下面的以5400、6400开头的错误码需要单独处理
5400002	App repeat login error	app重复登录	同一个appTid的app重复登录
5400003	appTid can not be empty	appTid不能为空	appTid不能为空
5400004	Authorization already exists	授权关系已存在	授权关系已存在
5400005	Authorization does not exist	授权关系不存在	授权关系不存在
5400006	Bind failed due to network error	因网络原因绑定失败	因网络原因绑定失败
5400007	Bind failed due to timeout error	因超时原因绑定失败	因超时原因绑定失败
5400008	Can not bind other manufacture's device	无法绑定其他厂商设备	非公版用户无法绑定非该pid设备
5400009	Modified user profile failed	修改用户档案失败	修改用户档案失败
5400010	Check verify code error	校验code失败	校验code失败
5400011	You have reached your device's authorization limits	设备授权次数达到上限	设备授权次数达到上限，无法再次授权
5400012	Bind failed due to internal error	因内部错误绑定失败	因内部错误绑定失败，一般是因为bindKey不对或者是devTid不对
5400013	Bind failed due to repeat bind	因重复绑定绑定失败	因重复绑定绑定失败
5400014	Device does not belong to user	设备不属于用户	设备不再属于该用户
5400015	No such instruction error	没有这样的指令	没有这样的指令
5400016	Device can not repeat login	设备无法重复登录	设备无法同时登录
5400017	devTid can not be empty	devTid不能为空	devTid不能为空
5400018	Create timer task failed due to counts reach limit	创建定时预约次数达到上限	创建定时预约次数达到上限
5400019	Instruction expired	授权的指令已过期	授权的指令已过期
5400020	Instruction not support	不支持该指令	不支持该指令，可能是指令填错了
5400021	Invalid email token	不合法的邮件token	不合法的邮件token
5400022	Invalid old password	不合法的旧密码	不合法的旧密码
5400023	Invalid verify code	不合法的校验code	不合法的校验code
5400024	Device does not found due to internal error, please reconnect	由于内部错误设备无法找到，请重连
5400025	No such manufacture id	不存在该pid	不存在该pid
5400026	No permission to access the instruction	没有对该指令的权限	没有对该指令的权限
5400027	Template with given id does not exist	指定模板不存在	指定模板不存在
5400028	Device does not found due to incorrect status	由于内部不正确的状态导致设备无法被找到
5400035	TaskId does not exist	指定任务不存在	指定任务不存在
5400036	Can not create duplicate template	无法创建重复模板	无法创建重复模板
5400037	devTid not match	设备id 不匹配	报文填写的devTid与登录设备的devTid不一致
5400039	User does not exist	用户不存在	用户不存在
5400045		短码或者短码密码错误
5400046		短码不足（系统错误）
5400047		无权修改其他用户绑定设备
5400043	Device can not force bind	设备无法强制绑定	设备无法强制绑定
5500000	Internal error	内部错误	内部服务错误
6400001	Reverse auth template with given id does not exist	指定id的反向注册申请不存在	请求已经被同意或拒绝
6400002	Invalid reverse authorization request	不合法的反向授权请求	设备此时已经不属于该授权者；调用者不是授权者；反向授权请求id错误
6400003	Only owner can authorize	只有属主可以授权设备给其他人	非属主尝试授权设备给其他人
6400004	Device with given devTid does not exist	指定devTid的设备不存在	操作不存在的设备
6400005	Reached the maximum number of device the folder can hold	达到文件夹所能容纳设备数量的上限	达到文件夹所能容纳设备数量的上限
6400006	Can not create duplicate template folder	无法创建同名文件夹	创建同名文件夹
6400007	Folder with given id does not exist	指定id的文件夹不存在	操作不存在的文件夹
6400008	Reached the maximum number of folder the user can create	达到创建文件夹数量上限	达到创建文件夹数量上限
6400009	Can not remove root folder	无法删除根目录	删除根目录
6400010	Can not rename root folder	无法给根目录改名	给根目录改名
6400011	Rule with given id does not exist	指定的规则不存在	操作不存在的规则
6400012	Scheduler task with given id does not exist	指定的定时预约任务不存在	操作不存在的定时预约任务
6400013	Can not create duplicate rule	无法创建相同的规则	创建相同的规则
6400014	Can not create duplicate scheduler task	无法创建相同的定时预约	创建相同的定时预约
6400015	Invalid prodPubKey	不合法的产品公共秘钥	不合法的产品公共秘钥
6400016	Has no privilege do that	没有权限这样做	操作没有权限
6400017	Invalid Param {0}	参数错误	请求参数错误
6400018	Cloud storage file with given name does not exist	指定的网盘文件不存在	操作不存在的网盘文件
6400020	Can not find this infrared code	找不到这个红外码	操作不存在的红外码
6400021	Infrared code request without response	红外服务请求出错
6400022	Can not find instruction set	无法找到指令集	操作不存在的指令集
6400023	Request params not supported	参数不支持	请求参数错误
6400024	Translating Json to String failure	解析json失败
6400025	Scheduler not supported	不支持定时预约	该设备不支持定时预约功能
6500001	Delete cloud storage file failed	删除网盘文件失败	网盘操作失败
6500002	Upload cloud storage file failed	上传网盘文件失败	网盘操作失败
6500003	Server use httpClient invoke failed	http网络调用失败	http调用失败