为了构建更好的平台生态环境，我们推出了基于OAuth2的API版本。
API 接口使用方式以及Url都参照GitHub，为了各位开发者更好的兼容已经存在的第三方应用。

# API 使用条款

未经用户允许，不准爬取或存储用户的资源。
禁止滥用 API，请求频率过快将导致请求终止。
OAuth2 认证基本流程
![image](./oauth2.png)

# OAuth2 获取 AccessToken 认证步骤

### 1. 授权码模式
* 应用通过 浏览器 或 Webview 将用户引导到平台三方认证页面上（ GET请求 ）

    `https://gitlink.org.cn/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code`

* 用户对应用进行授权
注意: 如果之前已经授权过的需要跳过授权页面，需要在上面第一步的 URL 加上 scope 参数，且 scope 的值需要和用户上次授权的勾选的一致。如用户在上次授权了user_info。则步骤A 中 GET 请求应为：

    `https://gitlink.org.cn/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope=user_info`

* 平台认证服务器通过回调地址`{redirect_uri}`将 用户授权码 传递给 应用服务器 或者直接在 Webview 中跳转到携带 用户授权码的回调地址上，Webview 直接获取code即可（`{redirect_uri}?code=abc&state=xyz`)
* 应用服务器 或 Webview 使用 access_token API 向平台认证服务器发送post请求传入 用户授权码 以及 回调地址（ POST请求 ）
注：请求过程建议将 client_secret 放在 Body 中传值，以保证数据安全。

    `https://gitlink.org.cn/oauth/token?grant_type=authorization_code&code={code}&client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}`

* 平台认证服务器返回 access_token
    
    应用通过 access_token 访问 Open API 使用用户数据。
    当 access_token 过期后（有效期为一天），你可以通过以下 refresh_token 方式重新获取 access_token（ POST请求 ）
    
    `https://gitlink.org.cn/oauth/token?grant_type=refresh_token&refresh_token={refresh_token}`

> 注意：如果获取 access_token 返回 403，可能是没有设置User-Agent的原因。
详见：获取Token时服务端响应状态403是什么情况

### 2. 密码模式
* 用户向客户端提供邮箱地址和密码。客户端将邮箱地址和密码发给平台认证服务器，并向平台认证服务器请求令牌。（ POST请求。Content-Type: application/x-www-form-urlencoded ）

    `curl -X POST --data-urlencode "grant_type=password" --data-urlencode "username={email}" --data-urlencode "password={password}" --data-urlencode "client_id={client_id}" --data-urlencode "client_secret={client_secret}" --data-urlencode "scope=user_info" https://gitlink.org.cn/oauth/token`

    scope表示权限范围，有以下选项，请求时使用空格隔开
    `user_info` `projects` `pull_requests` `issues` `notes` `keys` `hook groups` `gists` `enterprises`
* 认证服务器返回 access_token
应用通过 access_token 访问 Open API 使用用户数据。