|
|
# VBase API 文档
|
|
|
|
|
|
## 概述
|
|
|
|
|
|
VBase 是一个多租户身份认证与访问管理(IAM)系统，支持用户管理、组织管理、RBAC权限控制和OAuth2.0服务。
|
|
|
|
|
|
**基础信息**
|
|
|
- 基础URL: `https://api.example.com`
|
|
|
- 请求格式: `application/json`
|
|
|
- 响应格式: `application/json`
|
|
|
- 认证方式: Bearer Token (JWT)
|
|
|
|
|
|
**通用响应格式**
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"message": "success",
|
|
|
"data": {}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误响应**
|
|
|
```json
|
|
|
{
|
|
|
"code": 400,
|
|
|
"message": "error message",
|
|
|
"data": null
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 认证相关
|
|
|
|
|
|
### 用户登录
|
|
|
|
|
|
**POST** `/auth/login`
|
|
|
|
|
|
用户登录获取访问令牌。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| username | string | 是 | 用户名/邮箱/手机号 |
|
|
|
| password | string | 是 | 密码 |
|
|
|
| remember | bool | 否 | 记住登录 |
|
|
|
|
|
|
**响应示例**
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"data": {
|
|
|
"access_token": "eyJhbGciOiJIUzI1NiIs...",
|
|
|
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
|
|
|
"token_type": "Bearer",
|
|
|
"expires_in": 3600,
|
|
|
"user": {
|
|
|
"id": "user-id",
|
|
|
"username": "admin",
|
|
|
"nickname": "管理员",
|
|
|
"email": "admin@example.com",
|
|
|
"avatar": "https://..."
|
|
|
}
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 用户注册
|
|
|
|
|
|
**POST** `/auth/register`
|
|
|
|
|
|
注册新用户。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| username | string | 是 | 用户名(2-50字符) |
|
|
|
| password | string | 是 | 密码(至少8位) |
|
|
|
| email | string | 否 | 邮箱 |
|
|
|
| phone | string | 否 | 手机号 |
|
|
|
| nickname | string | 否 | 昵称 |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 刷新Token
|
|
|
|
|
|
**POST** `/auth/refresh`
|
|
|
|
|
|
使用刷新令牌获取新的访问令牌。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| refresh_token | string | 是 | 刷新令牌 |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 用户登出
|
|
|
|
|
|
**POST** `/auth/logout`
|
|
|
|
|
|
用户登出，使当前Token失效。
|
|
|
|
|
|
**请求头**
|
|
|
- Authorization: Bearer {access_token}
|
|
|
|
|
|
---
|
|
|
|
|
|
### 支持的第三方登录提供商
|
|
|
|
|
|
**GET** `/auth/providers`
|
|
|
|
|
|
获取系统支持的第三方登录提供商列表。
|
|
|
|
|
|
**响应示例**
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"data": [
|
|
|
{
|
|
|
"name": "google",
|
|
|
"display_name": "Google",
|
|
|
"icon": "google",
|
|
|
"enabled": true
|
|
|
},
|
|
|
{
|
|
|
"name": "github",
|
|
|
"display_name": "GitHub",
|
|
|
"icon": "github",
|
|
|
"enabled": true
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 第三方登录授权
|
|
|
|
|
|
**GET** `/auth/authorize/thirdparty`
|
|
|
|
|
|
获取第三方登录授权URL。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| provider | string | 是 | 提供商: google/github/wechat |
|
|
|
| redirect | string | 否 | 登录成功后重定向地址 |
|
|
|
| bind_mode | bool | 否 | 是否为绑定模式 |
|
|
|
|
|
|
**响应示例**
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"data": {
|
|
|
"auth_url": "https://github.com/login/oauth/authorize?...",
|
|
|
"state": "random-state-string"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 第三方登录回调
|
|
|
|
|
|
**GET** `/auth/callback/{provider}`
|
|
|
|
|
|
处理第三方登录回调。
|
|
|
|
|
|
**路径参数**
|
|
|
- provider: 提供商名称
|
|
|
|
|
|
**查询参数**
|
|
|
- code: 授权码
|
|
|
- state: 状态值
|
|
|
|
|
|
**响应示例（已绑定）**
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"data": {
|
|
|
"need_bind": false,
|
|
|
"access_token": "eyJhbGciOiJIUzI1NiIs...",
|
|
|
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
|
|
|
"token_type": "Bearer",
|
|
|
"expires_in": 3600,
|
|
|
"user": {...}
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例（未绑定）**
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"data": {
|
|
|
"need_bind": true,
|
|
|
"provider": "github",
|
|
|
"provider_id": "12345",
|
|
|
"auth_url": "/auth/bind?token=xxx"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 绑定第三方账号
|
|
|
|
|
|
**POST** `/auth/bind`
|
|
|
|
|
|
将第三方账号绑定到已有账号。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| temp_token | string | 是 | 临时绑定令牌 |
|
|
|
| username | string | 是 | 用户名/邮箱/手机号 |
|
|
|
| password | string | 是 | 密码 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 当前用户
|
|
|
|
|
|
### 获取当前用户信息
|
|
|
|
|
|
**GET** `/me`
|
|
|
|
|
|
获取当前登录用户的信息。
|
|
|
|
|
|
**请求头**
|
|
|
- Authorization: Bearer {access_token}
|
|
|
|
|
|
**响应示例**
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"data": {
|
|
|
"id": "user-id",
|
|
|
"username": "admin",
|
|
|
"nickname": "管理员",
|
|
|
"email": "admin@example.com",
|
|
|
"avatar": "https://...",
|
|
|
"status": 1,
|
|
|
"email_verified": true
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 更新当前用户信息
|
|
|
|
|
|
**PATCH** `/me`
|
|
|
|
|
|
更新当前用户的基本信息。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| nickname | string | 否 | 昵称 |
|
|
|
| avatar | string | 否 | 头像URL |
|
|
|
| email | string | 否 | 邮箱 |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 修改密码
|
|
|
|
|
|
**POST** `/me/change-password`
|
|
|
|
|
|
修改当前用户密码。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| old_password | string | 是 | 旧密码 |
|
|
|
| new_password | string | 是 | 新密码(至少8位) |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 获取第三方绑定列表
|
|
|
|
|
|
**GET** `/me/bindings`
|
|
|
|
|
|
获取当前用户绑定的第三方账号列表。
|
|
|
|
|
|
**响应示例**
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"data": [
|
|
|
{
|
|
|
"provider": "github",
|
|
|
"provider_name": "GitHub User",
|
|
|
"avatar": "https://...",
|
|
|
"email": "user@example.com",
|
|
|
"created_at": "2024-01-01 10:00:00"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 解绑第三方账号
|
|
|
|
|
|
**DELETE** `/me/bindings/{provider}`
|
|
|
|
|
|
解除指定提供商的账号绑定。
|
|
|
|
|
|
**路径参数**
|
|
|
- provider: 提供商名称 (google/github/wechat)
|
|
|
|
|
|
---
|
|
|
|
|
|
## 用户管理
|
|
|
|
|
|
### 用户列表
|
|
|
|
|
|
**GET** `/users`
|
|
|
|
|
|
获取用户列表（需要权限）。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| page | int | 否 | 页码，默认1 |
|
|
|
| page_size | int | 否 | 每页数量，默认10 |
|
|
|
| keyword | string | 否 | 搜索关键词 |
|
|
|
| status | int | 否 | 状态筛选 |
|
|
|
|
|
|
**响应示例**
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"data": {
|
|
|
"items": [...],
|
|
|
"total": 100,
|
|
|
"page": 1,
|
|
|
"page_size": 10,
|
|
|
"total_pages": 10
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 创建用户
|
|
|
|
|
|
**POST** `/users`
|
|
|
|
|
|
创建新用户（需要权限）。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| username | string | 是 | 用户名 |
|
|
|
| password | string | 是 | 密码 |
|
|
|
| nickname | string | 否 | 昵称 |
|
|
|
| email | string | 否 | 邮箱 |
|
|
|
| phone | string | 否 | 手机号 |
|
|
|
| status | int | 否 | 状态 |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 获取用户详情
|
|
|
|
|
|
**GET** `/users/{user_id}`
|
|
|
|
|
|
获取指定用户的详细信息。
|
|
|
|
|
|
**路径参数**
|
|
|
- user_id: 用户ID
|
|
|
|
|
|
---
|
|
|
|
|
|
### 更新用户
|
|
|
|
|
|
**PATCH** `/users/{user_id}`
|
|
|
|
|
|
更新指定用户的信息。
|
|
|
|
|
|
**路径参数**
|
|
|
- user_id: 用户ID
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| nickname | string | 否 | 昵称 |
|
|
|
| avatar | string | 否 | 头像 |
|
|
|
| email | string | 否 | 邮箱 |
|
|
|
| phone | string | 否 | 手机号 |
|
|
|
| status | int | 否 | 状态 |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 删除用户
|
|
|
|
|
|
**DELETE** `/users/{user_id}`
|
|
|
|
|
|
删除指定用户（软删除）。
|
|
|
|
|
|
---
|
|
|
|
|
|
### 更新用户状态
|
|
|
|
|
|
**PATCH** `/users/{user_id}/status`
|
|
|
|
|
|
更新用户状态。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| status | int | 是 | 0:禁用 1:正常 2:未激活 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 组织管理
|
|
|
|
|
|
### 组织列表
|
|
|
|
|
|
**GET** `/orgs`
|
|
|
|
|
|
获取当前用户的组织列表。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| page | int | 否 | 页码 |
|
|
|
| page_size | int | 否 | 每页数量 |
|
|
|
| keyword | string | 否 | 搜索关键词 |
|
|
|
|
|
|
**响应示例**
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"data": {
|
|
|
"items": [
|
|
|
{
|
|
|
"id": "org-id",
|
|
|
"name": "技术部",
|
|
|
"code": "tech",
|
|
|
"owner_id": "user-id",
|
|
|
"path": "/tech",
|
|
|
"level": 0,
|
|
|
"status": 1,
|
|
|
"my_roles": ["admin"],
|
|
|
"my_status": 1
|
|
|
}
|
|
|
],
|
|
|
"total": 10
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 创建组织
|
|
|
|
|
|
**POST** `/orgs`
|
|
|
|
|
|
创建新组织。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| name | string | 是 | 组织名称 |
|
|
|
| code | string | 是 | 组织编码(唯一) |
|
|
|
| parent_id | string | 否 | 父组织ID |
|
|
|
| description | string | 否 | 描述 |
|
|
|
| max_members | int | 否 | 最大成员数 |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 获取组织详情
|
|
|
|
|
|
**GET** `/orgs/{org_id}`
|
|
|
|
|
|
获取组织详细信息。
|
|
|
|
|
|
---
|
|
|
|
|
|
### 更新组织
|
|
|
|
|
|
**PATCH** `/orgs/{org_id}`
|
|
|
|
|
|
更新组织信息（仅所有者）。
|
|
|
|
|
|
---
|
|
|
|
|
|
### 删除组织
|
|
|
|
|
|
**DELETE** `/orgs/{org_id}`
|
|
|
|
|
|
删除组织（仅所有者，需无子组织）。
|
|
|
|
|
|
---
|
|
|
|
|
|
### 组织树
|
|
|
|
|
|
**GET** `/orgs/tree`
|
|
|
|
|
|
获取当前用户的组织树结构。
|
|
|
|
|
|
**响应示例**
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"data": [
|
|
|
{
|
|
|
"id": "org-id",
|
|
|
"name": "总公司",
|
|
|
"children": [
|
|
|
{
|
|
|
"id": "sub-org-id",
|
|
|
"name": "技术部"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 组织成员列表
|
|
|
|
|
|
**GET** `/orgs/{org_id}/members`
|
|
|
|
|
|
获取组织成员列表。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| page | int | 否 | 页码 |
|
|
|
| page_size | int | 否 | 每页数量 |
|
|
|
| status | int | 否 | 状态筛选 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## OAuth2.0 服务端
|
|
|
|
|
|
### 授权端点
|
|
|
|
|
|
**GET** `/oauth/authorize`
|
|
|
|
|
|
OAuth2.0 授权端点，获取授权码。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| response_type | string | 是 | code/token |
|
|
|
| client_id | string | 是 | 客户端ID |
|
|
|
| redirect_uri | string | 是 | 回调地址 |
|
|
|
| scope | string | 否 | 权限范围 |
|
|
|
| state | string | 是 | CSRF防护 |
|
|
|
| code_challenge | string | 否 | PKCE挑战码 |
|
|
|
| code_challenge_method | string | 否 | S256/plain |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 令牌端点
|
|
|
|
|
|
**POST** `/oauth/token`
|
|
|
|
|
|
OAuth2.0 令牌端点，交换授权码获取访问令牌。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| grant_type | string | 是 | authorization_code/refresh_token/client_credentials |
|
|
|
| code | string | 条件 | 授权码 |
|
|
|
| redirect_uri | string | 条件 | 回调地址 |
|
|
|
| client_id | string | 是 | 客户端ID |
|
|
|
| client_secret | string | 是 | 客户端密钥 |
|
|
|
| refresh_token | string | 条件 | 刷新令牌 |
|
|
|
| code_verifier | string | 条件 | PKCE验证器 |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 撤销令牌
|
|
|
|
|
|
**POST** `/oauth/revoke`
|
|
|
|
|
|
撤销访问令牌或刷新令牌。
|
|
|
|
|
|
---
|
|
|
|
|
|
### 令牌内省
|
|
|
|
|
|
**POST** `/oauth/introspect`
|
|
|
|
|
|
查询令牌信息（RFC 7662）。
|
|
|
|
|
|
---
|
|
|
|
|
|
### 用户信息
|
|
|
|
|
|
**GET** `/oauth/userinfo`
|
|
|
|
|
|
OIDC 用户信息端点。
|
|
|
|
|
|
---
|
|
|
|
|
|
### OIDC 发现文档
|
|
|
|
|
|
**GET** `/.well-known/openid-configuration`
|
|
|
|
|
|
获取 OIDC 配置信息。
|
|
|
|
|
|
---
|
|
|
|
|
|
### JWKS
|
|
|
|
|
|
**GET** `/oauth/jwks`
|
|
|
|
|
|
获取 JWT 签名公钥。
|
|
|
|
|
|
---
|
|
|
|
|
|
## OAuth 客户端管理
|
|
|
|
|
|
### 客户端列表
|
|
|
|
|
|
**GET** `/oauth/clients`
|
|
|
|
|
|
获取 OAuth 客户端列表。
|
|
|
|
|
|
---
|
|
|
|
|
|
### 创建客户端
|
|
|
|
|
|
**POST** `/oauth/clients`
|
|
|
|
|
|
创建新的 OAuth 客户端。
|
|
|
|
|
|
**请求参数**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| name | string | 是 | 应用名称 |
|
|
|
| description | string | 否 | 描述 |
|
|
|
| redirect_uris | []string | 是 | 回调地址列表 |
|
|
|
| grant_types | []string | 否 | 授权类型 |
|
|
|
| allowed_scopes | []string | 否 | 允许的范围 |
|
|
|
|
|
|
**响应示例**
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"data": {
|
|
|
"id": "client-id",
|
|
|
"name": "My App",
|
|
|
"client_id": "abc123...",
|
|
|
"client_secret": "secret...",
|
|
|
"redirect_uris": ["https://app.com/callback"],
|
|
|
"grant_types": ["authorization_code", "refresh_token"]
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 获取客户端详情
|
|
|
|
|
|
**GET** `/oauth/clients/{client_id}`
|
|
|
|
|
|
获取 OAuth 客户端详情。
|
|
|
|
|
|
---
|
|
|
|
|
|
### 更新客户端
|
|
|
|
|
|
**PATCH** `/oauth/clients/{client_id}`
|
|
|
|
|
|
更新 OAuth 客户端信息。
|
|
|
|
|
|
---
|
|
|
|
|
|
### 删除客户端
|
|
|
|
|
|
**DELETE** `/oauth/clients/{client_id}`
|
|
|
|
|
|
删除 OAuth 客户端。
|
|
|
|
|
|
---
|
|
|
|
|
|
### 重新生成密钥
|
|
|
|
|
|
**POST** `/oauth/clients/{client_id}/regenerate-secret`
|
|
|
|
|
|
重新生成客户端密钥。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 请求头说明
|
|
|
|
|
|
### 认证头
|
|
|
|
|
|
```
|
|
|
Authorization: Bearer {access_token}
|
|
|
```
|
|
|
|
|
|
### 组织上下文
|
|
|
|
|
|
```
|
|
|
X-Org-ID: {organization_id}
|
|
|
```
|
|
|
|
|
|
用于指定当前操作的组织上下文。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 状态码说明
|
|
|
|
|
|
| 状态码 | 说明 |
|
|
|
|--------|------|
|
|
|
| 200 | 成功 |
|
|
|
| 400 | 请求参数错误 |
|
|
|
| 401 | 未认证 |
|
|
|
| 403 | 无权限 |
|
|
|
| 404 | 资源不存在 |
|
|
|
| 429 | 请求过于频繁 |
|
|
|
| 500 | 服务器内部错误 |
|