# 认证与授权API

用户与设备
为什么需要认证授权
如何认证授权
使用refresh_token获取新的AccessToken

# 用户与设备

用户是指购买厂商产品设备的消费者，是iFLYOS的用户，也是厂商的用户

设备是指厂商在设备接入平台 (opens new window)创建了设备后，将 Client ID 与自家的产品进行绑定，最终到达消费者手里的智能语音设备

# 为什么需要认证授权

通过 EVS协议或 IVS协议使用接入语音服务时，iFLYOS需要确认发起请求的是哪个用户通过哪个设备来请求的，有了这两个信息，我们可以更好的为返回更适合用户的指令，更好的帮助用户得到他们想要的答案、完成他们想要完成的事情。

# 如何认证授权

iFLYOS专门为设备提供了一套简易安全的授权流程，使得用户可以快速的授权设备。

如果厂商不方便接入iFLYOS账号，则需要使用第三方账号来接入iFLYOS。这种情况下，对于用户认证、设备授权的安全性，更多的由厂商的服务提供保证。点击查看第三方账号认证授权

# STEP1:设备申请授权

设备向iFLYOS的授权服务发起一个POST请求，表明需要授权：

请求地址: https://auth.iflyos.cn/oauth/ivs/device_code

请求必须包含以下参数：

client_id: 在设备接入平台 (opens new window)的设备信息里查看
scope: 固定值user_ivs_all
scope_data: 包含设备信息的 JSON，包含device_id字段
- device_id: 设备的唯一标识，建议使用设备SN作为device_id。

注意

scope_data字段需要进行URL编码
如果你是智能硬件设备，你需要在设备接入控制台 (opens new window)的设备ID页导入device_id列表，列表之外的device_id将会鉴权不通过。

{
    "user_ivs_all": {
        "device_id": "your device_id"
    }
}

curl示例：

curl -X POST \
  https://auth.iflyos.cn/oauth/ivs/device_code \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'client_id={{client_id}}&scope=user_ivs_all&scope_data=%7B%22user_ivs_all%22%3A%20%7B%22device_id%22%3A%20%20%2212345%22%7D%7D'

返回数据：

{
    "verification_uri": "https://auth.iflyos.cn/oauth/device",
    "user_code": "W6EBOU",
    "interval": 5,
    "expires_in": 600,
    "device_code": "0w21Wk2_FTnKmCyV1TqbiwauUrJjr9UiosIE-8Ka7f7zi5hCtv9zxEymGjNaXI9h"
}

参数	类型	说明
verification_uri	String	用户校验`用户授权码`的链接地址
user_code	String	简短的`用户授权码`
interval	Integer	请求时间间隔
expires_in	Integer	`用户授权码`有效时间，单位为秒
device_code	String	`设备授权码`

# STEP2:用户授权

# 2.1

设备通过STEP 1的请求，(通过某种方式)将授权链接和用户授权码组装发送到用户端，

让用户访问最终链接：

{{verification_uri}}?user_code={{user_code}}

例如： https://auth.iflyos.cn/oauth/device?user_code=W6EBOU

# 2.2

用户打开以上链接后，首先需要进行登录(无需注册，使用手机验证码进行登录)，登录成功后，会出现类似以下【确认授权】的页面：

提醒

用户可以选择授权或者拒绝
测试调试阶段，请在设备接入控制台 (opens new window)的设备测试页添加手机号白名单，否则将会造成授权失败。

scopes

# STEP3:设备获取 AccessToken

注意

该步骤与Step 2是同步进行的

设备通过STEP 1的请求，获取到设备授权码，使用该授权码，轮循调用授权服务的接口，检测授权状态并获取AccessToken：

POST /oauth/ivs/token HTTP/1.1
Host: auth.iflyos.cn
Content-Type: application/json

{
	"client_id": "YOUR_CLIENT_ID",
	"grant_type": "urn:ietf:params:oauth:grant-type:device_code",
	"device_code": "YOUR_DEVICE_CODE"
}

curl示例：

curl -X POST \
  https://auth.iflyos.cn/oauth/ivs/token \
  -H 'content-type: application/json' \
  -d '{
	"client_id": "8d3d13ab-aea8-4595-ac4f-dda3f524450c",
	"grant_type": "urn:ietf:params:oauth:grant-type:device_code",
	"device_code": "8JyTH0Jm3yg_SavmvJ4WzGWgjnNlRNu2jV0oq--6nZW0OImk2jBEXdMeYpQuEkie"
}'

返回数据可能是：

用户未授权，等待下一次轮循请求

{
    "error": "authorization_pending"
}

授权码过期，用户仍未授权

{
    "error": "expired_token"
}

用户拒绝授权

{
    "error": "access_denied"
}

用户通过授权

{
    "token_type": "bearer",
    "refresh_token": "4_vujpFOfu0G5yf4**************DwX5S80s74CY7",
    "expires_in": 86400000,
    "created_at": 1526485197,
    "access_token": "bd6XMEqzIokI6mnMM**************iKAdYNa9T-1WXY"
}

参数	类型	说明
token_type	String	固定值，`bearer`
access_token	String	接入`iFLYOS`的令牌
refresh_token	String	用于刷新AccessToken的令牌
expires_in	long	AccessToken的有效时长，单位为秒
created_at	long	令牌创建时间

# 授权完成

至此，用户授权流程完成，这是一个标准的OAuth2设备授权流程，具体协议可以参考：https://oauth.net/2/grant-types/device-code

整体授权流程：

auth

# 使用refresh_token获取新的AccessToken

当AccessToken失效时，可以使用通过授权后获取到的refresh_token来获取新的AccessToken，同时返回的refresh_token可用于下次刷新。

POST /oauth/ivs/token HTTP/1.1
Host: auth.iflyos.cn
Content-Type: application/json

{
	"grant_type": "refresh_token",
	"refresh_token": "_NS6qnBUdJep*******************4ZZmBSP4Pbfy-jav4n3EiX"
}

curl示例：

curl -X POST \
  https://auth.iflyos.cn/oauth/ivs/token \
  -H 'content-type: application/json' \
  -d '{
	"grant_type": "refresh_token",
	"refresh_token": "_NS6qnBUdJep*******************4ZZmBSP4Pbfy-jav4n3EiX"
}'

返回数据可能是：

refresh_token无效

{
    "message": "refresh token错误",
    "error": "invalid_refresh_token"
}

刷新token成功

{
    "token_type": "bearer",
    "refresh_token": "4_vujpFOfu0G5yf4**************DwX5S80s74CY7",
    "expires_in": 86400000,
    "created_at": 1526485197,
    "access_token": "bd6XMEqzIokI6mnMM**************iKAdYNa9T-1WXY"
}

← 第三方账号接入红外控制API →