i8小时开放平台

简介

i8小时为企业提供了一个社交化办公协作平台。基于此平台上,开发者对应用进行无限的灵活扩展开发, 企业也可以围绕i8系统基础平台,将i8小时所使用的应用数据与线下私有应用进行对接。为此,i8小时一开始就将开放平台的理念植入产品设计。 基于i8小时开放平台,企业和第三方开发者均可设计和开发扩展应用。 第三方开发者通过加入i8小时应用市场可以获得强大的应用推广支持,快速获得客户和收入。

架构介绍

在i8小时开放平台上,我们为您提供了社区接口、工作流、人事等一系列数据读写接口, 广大的企业和第三方开发者只需登录此平台并申请创建应用, 即可通过授权令牌调用数据接口进行数据的读取与操作。

我们的目标是使您能够完全聚焦在自己的应用开发层面上, 也非常鼓励企业和第三方开发者依照i8小时平台的社会化沟通协作的特性, 开发出具有创新、解决企业迫切需求的应用。 另外,i8小时将和企业与第三方开发者共享在i8小时平台上的收益,实现共赢。

开发流程

i8小时开放平台开发者注册完成并登录创建应用应用数据对接网站帐号接入获取访问令牌i8应用数据凭accessTokeni8帐户信息调用数据接口获取访问令牌第三方应用调用帐户信息第三方站点凭accessToken

开发者协议

约定

本协议是i8小时应用开发者或者提供方与i8小时运营企业的协议。 i8小时应用开发者或者提供方是指在i8小时开放平台申请应用开发的个人或者企业,任何应用都必须遵守本协议的约束。

权利与义务

i8小时开放平台知识产权属于上海汇明信息技术有限公司, 在i8小时开放平台登记的应用知识产权属于i8小时应用开发者或者提供方 i8小时有权免费获得应用的使用权,并允许i8小时用户在安装和使用该应用 第三方应用登录i8小时应用市场前,i8小时开放平台需要对应用进行规范审核,对于不符合国家相关法律法规的应用, 将通过各种形式进行处理,直至关闭数据接口和下线处理,由此产生的损失由应用开发者或者提供方自行承担。 应用开发者或者提供方在申请应用之后,如90天内没有数据接口的使用,i8小时开放平台有权利停止该应用接口使用权限并删除该应用 应用开发者可以在i8小时开放平台免费申请应用开发,i8小时开放平台会自动分配应用授权码,应用开发者通过授权码调用数据接口,读写i8小时平台数据 应用在通过i8小时开放平台规范审核上线后,允许用户在i8小时应用市场安装和使用该应用,应用的计费遵循既定的收费与定价方式

响应状态代码

i8小时开放平台,所有接口请求响应数据格式为JSON

JSON格式:
{ "status":"状态码", "ReturnObject":"返回结果对象", "Description":"状态描述" }
状态码状态描述含义
200 正常
400 请求不存在
500 服务器内部错误
101 无效请求
102 response_type参数出错(必须为code)!
103 参数client_id或redirect_uri不存在!
104 无效参数client_id!
105 无效请求,redirect_uri不匹配!
106 无效请求,超出cope授权范围!
107 参数scope不存在!
108 参数code不存在!
109 参数grant_type不存在!
110 HTTP请求头Authorization不存在!
111 参数code不可用,或code已失效!
112 HTTP请求头authorization code不可用!
113 拒绝访问,请求头authorization验证信息不存在!
114 远程请求出错!
115 不可用的access_token!
116 acccess_token已失效!
117 HTTP请求头Authorization验证信息样式出错!
118 HTTP请求头不存在access_token验证信息
119 token_type与当前HTTP请求头Authorization信息不匹配
120 不存在参数refresh token
121 不存在参数redirect_uri
123 无效的grant_type参数
124 参数scope不存在
125 参数refresh_token已失效

OAuth 2.0认证

了解OAuth 2.0

i8小时开放平台支持 OAuth 2.0 协议的授权访问。关于 OAuth 2.0 协议规范,请参考

使用 OAuth 2.0 的流程可以简单概括为:

客户端(第三方)i8用户i8认证服务器i8数据资源服务器(A) 客户端认证请求(B) i8用户认证授权(C) 认证授权(D) 下发访问令牌(E) 凭令牌请求资源(F) 响应客户端资源

A, 应用客户端向i8小时平台请求,i8平台向客户端呈现登录授权页
B, 用户认证授权后,i8平台向客户端返回认证信息
C, 客户端凭上一步返回的认证信息与i8应用凭证,向i8认证服务器发起获取access_token(令牌)请求。
D, i8认证服务器验证通过后,向客户端返回access_token
E, 客户端凭access_token向i8数据资源服务器发起数据请求
F, i8服务器返回客户所请求数据


开发与使用

i8小时支持三种授权模式:
  • 授权码模式(authorization code)
  • 密码模式(resource owner password credentials)
  • 客户端模式(client credentials)

授权码模式(authorization code)
第一步,GET 请求/oauth2/v1/authorise (弹出用户授权登录框)
请求参数:
参数名描述含义
client_id 应用的唯一标识,对应于appID(必选)
response_type 响应类型,此处为code (必选)
scope 申请权限的范围 (必选)
redirect_uri 用户授权完成后的回调地址,应用需要通过此回调地址获得用户的授权结果。此地址必须与在应用注册时填写的回调地址一致。如:http://www.example.com/ (必选)
state 用来维护请求和回调状态的附加字符串,在授权完成回调时会附加此参数,应用可以根据此字符串来判断上下文关系。(可选)
如下:
GET /oauth2/v1/authorise?client_id=dd631edd-5c88-4960-914d-71f18962de30&response_type=code&scope=0&redirect_uri=http%3A%2F%2Fwww.example.com%2F&state=123456 HTTPS/1.1
Host: open.i8xiaoshi.com
Content-Type: application/x-www-form-urlencoded
第二步,根据用户登录,若登录验证成功,则跳转 https://www.example.com/?code=Uz98r4p76523feWaYewHmj53K2 (授权码code为10分钟有效期) 如下:
HTTPS/1.1 302 Found
Location: https://www.example.com/?code=Uz98r4p76523feWaYewHmj53K2
第三步,获取到code之后,POST 请求/oauth2/v1/token 客户端向i8小时服务器申请令牌
请求参数:
参数名描述含义
grant_type 授权模式,当前为“authorization_code”(必选)
client_id 应用的唯一标识,对应于appID (必选)
code 上一步获得的授权码 (必选)
redirect_uri 用户授权完成后的回调地址,应用需要通过此回调地址获得用户的授权结果。此地址必须与在应用注册时填写的回调地址一致。如:http://www.example.com/ (必选)
如下:
POST /oauth2/v1/token HTTPS/1.1
Host: open.i8xiaoshi.com
Authorization: Basic Uz98r4p76523feWaYewHmj53K2
Content-Type: application/x-www-form-urlencoded
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Form Data: grant_type=authorization_code&client_id=dd631edd-5c88-4960-914d-71f18962de30&redirect_uri=http%3A%2F%2Fwww.example.com%2F&code=Uz98r4p76523feWaYewHmj53K2

备注:HTTP头部信息"Authorization: Basic Uz98r4p76523feWaYewHmj53K2",其中的代码串为appid与secretid相加之后的sha1加密串,即"Authorization: Basic sha1(appid+secretid)",

第四步,若认证服务器通过,则HTTP响应数据格式为
参数名描述含义
access_token 访问令牌
token_type 令牌类型
expires_in 过期时间,单位为秒
refresh_token更新令牌,用来获取下一次的访问令牌
scope 权限范围
如下:
{"access_token": "83EtnFZFEjr1zCsicMWpAAFE","token_type": "bearer","expires_in": "1342342","refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA","scope": 1 }

密码模式(resource owner password credentials)
第一步,POST 请求/oauth2/v1/token 客户端向i8小时服务器申请令牌
请求参数:
参数名描述含义
grant_type 授权模式,当前为“password”(必选)
client_id 应用的唯一标识,对应于appID (必选)
scope 权限范围 (必选)
passportID 用户登录名 (必选)
password 用户登录密码 (必选)
POST /oauth2/v1/token HTTPS/1.1
Host: open.i8xiaoshi.com
Authorization: Basic Uz98r4p76523feWaYewHmj53K2
Content-Type: application/x-www-form-urlencoded
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Form Data: grant_type=password&client_id=dd631edd-5c88-4960-914d-71f18962de30&scope=0&passportID=user@exmail.com&password=12345678

备注:HTTP头部信息"Authorization: Basic Uz98r4p76523feWaYewHmj53K2",其中的代码串为appid与secretid相加之后的sha1加密串,即"Authorization: Basic sha1(appid+secretid)",

第二步,若认证服务器通过,则HTTP响应数据格式为(同授权码模式第四步 如下:
{"access_token": "83EtnFZFEjr1zCsicMWpAAFE","token_type": "bearer","expires_in": "1342342","refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA","scope": 1 }

客户端模式(client credentials)
第一步,POST 请求/oauth2/v1/token 客户端向i8小时服务器申请令牌 请求参数:
参数名描述含义
grant_type 授权模式,当前为“clientcredentials”(必选)
client_id 应用的唯一标识,对应于appID (必选)
scope 权限范围 (必选)
redirect_uri 用户授权完成后的回调地址,应用需要通过此回调地址获得用户的授权结果。此地址必须与在应用注册时填写的回调地址一致。如:http://www.example.com/ (必选)
POST /oauth2/v1/token HTTPS/1.1
Host: open.i8xiaoshi.com
Authorization: Basic Uz98r4p76523feWaYewHmj53K2
Content-Type: application/x-www-form-urlencoded
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Form Data: grant_type=clientcredentials&client_id=dd631edd-5c88-4960-914d-71f18962de30&scope=0&redirect_uri=http%3A%2F%2Fwww.example.com%2F

备注:HTTP头部信息"Authorization: Basic Uz98r4p76523feWaYewHmj53K2",其中的代码串为appid与secretid相加之后的sha1加密串,即"Authorization: Basic sha1(appid+secretid)",

第二步,若认证服务器通过,则HTTP响应数据格式为(同授权码模式第四步 如下:
{"access_token": "83EtnFZFEjr1zCsicMWpAAFE","token_type": "bearer","expires_in": "1342342","refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA","scope": 1 }

刷新令牌(refresh access_token)
第一步,POST 请求/oauth2/v1/token 客户端向i8小时服务器刷新令牌 请求参数:
参数名描述含义
grant_type 授权模式,当前为“refresh_token”(必选)
client_id 应用的唯一标识,对应于appID (必选)
refresh_token刷新token令牌
scope 权限范围 (必选)
redirect_uri 用户授权完成后的回调地址,应用需要通过此回调地址获得用户的授权结果。此地址必须与在应用注册时填写的回调地址一致。如:http://www.example.com/ (必选)
POST /oauth2/v1/token HTTPS/1.1
Host: open.i8xiaoshi.com
Authorization: Basic Uz98r4p76523feWaYewHmj53K2
Content-Type: application/x-www-form-urlencoded
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Form Data: grant_type=refresh_token&client_id=dd631edd-5c88-4960-914d-71f18962de30&scope=0&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&redirect_uri=http%3A%2F%2Fwww.example.com%2F

备注:HTTP头部信息"Authorization: Basic Uz98r4p76523feWaYewHmj53K2",其中的代码串为appid与secretid相加之后的sha1加密串,即"Authorization: Basic sha1(appid+secretid)",

第二步,若认证服务器通过,则HTTP响应数据格式为(同授权码模式第四步 如下:
{"access_token": "83EtnFZFEjr1zCsicMWpAAFE","token_type": "bearer","expires_in": "1342342","refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA","scope": 1 }

凭令牌(access_token)访问数据接口

当获取到accessToken之后,再将有效的accessToken放于Http头部,设为Authorization属性值,格式为"Authorization:[tokenType] [accessToken]",如下请求成员信息接口:

GET /com/user/info?userId=c5f22cfc-cf70-49ec-9955-106562d03904 HTTPS/1.1
Host: oapi.i8xiaoshi.com
Authorization: Bearer 83EtnFZFEjr1zCsicMWpAAFE
Content-Type: application/json;charset=utf-8