接口说明
文档版本：v1.0协议支持：OAuth 2.0 Authorization Code 授权码模式
一、概述
软柠通行证（Rutno ID）为第三方应用提供标准化的 OAuth 2.0 授权登录能力。开发者可通过接入 Rutno ID，快速实现用户授权登录、获取用户基础信息，降低账号体系开发成本。
二、接入准备
2.1 开放平台注册应用
申请入口：https://open.rutno.com前置条件：
- 已注册并登录软柠账号
- 账号已完善公司信息
2.2 应用信息填写
创建应用时需提交：
- 客户端名称
- 客户端描述
- 客户端分类
- 客户端官网
- 客户端 ICON（正方形，创建后不可修改）
- 授权回调地址（Redirect URI）
- ICP 备案号（可选）
2.3 获取应用凭证
应用创建成功后，系统将下发：
- client_id：应用唯一标识
- client_secret：应用密钥（严禁泄露、不可明文暴露在前端）
三、授权流程（标准 OAuth 2.0 授权码模式）
重要说明
- 全程使用 HTTPS
- 授权码 code 一次性有效，短时有效
四、接口详情
4.1 获取授权码
请求地址plaintext
GET https://id.rutno.com/rn-oauth/authorize
必传参数表格
| 参数名 | 必选 | 说明 |
| client_id | 是 | 应用 ID |
| redirect_uri | 是 | 回调地址，必须与平台配置一致 |
| response_type | 是 | 固定值：code |
| scope | 否 | 权限域，多个用空格分隔 |
| state | 否 | 随机字符串，防 CSRF，建议必传 |
请求示例plaintext
https://id.rutno.com/rn-oauth/authorize
?client_id=YOUR_CLIENT_ID
&redirect_uri=https://your-domain.com/callback
&response_type=code
&scope=username email avatar
&state=random_string
成功回调plaintext
https://your-domain.com/callback?code=xxx&state=xxx
4.2 使用 code 换取 AccessToken
请求地址plaintext
POST https://id.rutno.com/rn-oauth/token
请求头plaintext
Content-Type: application/x-www-form-urlencoded
参数表格
| 参数名 | 必选 | 说明 |
| grant_type | 是 | authorization_code |
| client_id | 是 | 应用 ID |
| client_secret | 是 | 应用密钥 |
| code | 是 | 上一步获取的授权码 |
| redirect_uri | 是 | 与第一步一致 |
成功返回json
{
"access_token": "AT_xxx",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "RT_xxx",
"scope": "username email avatar"
}
4.3 获取用户信息
请求地址plaintext
GET / POST https://id.rutno.com/rn-oauth/userinfo
请求头plaintext
Authorization: Bearer YOUR_ACCESS_TOKEN
成功返回json
{
"sub": "10001",
"id": "10001",
"username": "user_demo",
"nickname": "演示用户",
"email": "demo@example.com",
"avatar": "https://id.rutno.com/useravatar/demo.jpg",
"phone": "13800138000",
"gender": "1",
"region": "CN",
"bio": "Hello World"
}
五、权限域（Scope）说明
支持的 Scope 与用户字段对应：表格
| Scope | 说明 |
| id | 用户 ID |
| account_id | 账户 ID |
| username | 用户名 |
| nickname | 昵称 |
| 邮箱 | |
| phone | 手机 |
| avatar | 头像 |
| gender | 性别 |
| birthday | 生日 |
| region | 地区 |
| bio | 个人简介 |
多个权限使用空格分隔。
六、错误码说明
表格
| 错误码 | 含义 |
| invalid_client | client_id /client_secret 错误 |
| invalid_grant | 授权码无效 / 过期 |
| unauthorized_client | 应用无权限使用此授权类型 |
| access_denied | 用户或服务端拒绝授权 |
错误通常返回 HTTP 400 / 401。
七、安全建议
- client_secret 只在后端使用，绝不暴露到前端
- state 参数建议每次生成随机值，用于防 CSRF
- 回调地址必须在平台白名单中配置
- access_token 建议本地加密存储
- 授权码 code 只能使用一次