房东需要先在百居易注册账号。百居易对外接入采用 OAuth 2.0,由每位房东决定是否授权你的应用管理其房间。
授权流程
要发起授权,需要在你的应用里向房东展示一个授权入口(按钮或链接)。整个流程如下:
- 房东点击授权按钮 / 链接。
- 浏览器跳转到百居易站点;若房东未登录,需要先登录百居易账号。
- 房东查看你的应用申请访问的数据范围,可以选择 允许 或 拒绝。
- 如果房东允许,会跳转回你应用配置的 Redirect URL,并附上一个 授权码(authorization code)——可用它换取 access token 和 refresh token。
- 如果房东拒绝,授权流程终止,应用与该房东之间不会建立连接。
第 4 步拿到的 access token 用于代表该房东调用 API,每 7 天需要刷新一次以保持有效。详细的换取 / 刷新方式见 获取 / 刷新 Token API。
配置 Redirect URL
接入 OAuth 前,必须先配置 Redirect URL。这是房东完成授权后跳转回去的地址。
新增或修改 Redirect URL 请联系 百居易客服 ——出于安全考虑需要人工审核。
构造授权链接
房东在浏览器里通过 GET 请求以下地址完成授权:
https://www.myhostex.com/app/authorization?client_id={your_client_id}&redirect_uri={your_redirect_url}&state={whatever_you_want}
state参数是 OAuth 用来防御 跨站请求伪造(CSRF) 的安全机制。由客户端生成一个唯一字符串,在跳回时原样返回,客户端必须校验返回值与原始值一致再继续后续流程。
让房东可以撤销授权
如果房东决定不再使用你的应用,必须能彻底解除关联。
提供撤销入口有两种方式:在你的应用内提供撤销按钮,房东点击后由你的应用调用 撤销 / 删除 Token API 撤销其 access token 和 refresh token;或者引导房东到 百居易后台 自行撤销。
