应用管理 API

应用管理接口用于管理平台中注册的 OIDC 客户端应用，包括应用的增删改查和客户端密钥轮换。

所有接口均需要管理员令牌认证：Authorization: Bearer <admin_token>

应用类型

类型	值	说明
Traditional	Traditional	传统 Web 应用（服务端渲染，拥有后端）
SPA	SPA	单页应用（纯前端，无后端）
Native	Native	原生应用（移动端、桌面端）
MachineToMachine	MachineToMachine	机器对机器（后端服务间通信）

---

获取应用列表

GET /api/v1/applications

分页获取应用列表。

查询参数：

参数	类型	必填	默认值	说明
page	integer	否	1	页码
page_size	integer	否	20	每页条数

请求示例：

curl -X GET "https://your-domain/api/v1/applications?page=1&page_size=10" \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "data": [
      {
        "id": "app_001",
        "name": "My Web App",
        "type": "Traditional",
        "description": "Main web application",
        "client_id": "cbc_app_x7k9m2n4p1",
        "oidc_client_metadata": {
          "redirect_uris": ["https://app.example.com/callback"],
          "grant_types": ["authorization_code", "refresh_token"]
        },
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
      }
    ],
    "total": 3,
    "page": 1,
    "page_size": 10
  }
}

---

创建应用

POST /api/v1/applications

创建一个新的 OIDC 客户端应用。创建成功后会返回 client_id 和 client_secret。

注意： client_secret 仅在创建时返回一次，请妥善保管。

请求体：

字段	类型	必填	说明
name	string	是	应用名称
type	string	是	应用类型：Traditional、SPA、Native、MachineToMachine
description	string	否	应用描述
oidc_client_metadata	object	否	OIDC 客户端配置
oidc_client_metadata.redirect_uris	string[]	否	授权回调地址列表
oidc_client_metadata.grant_types	string[]	否	授权类型列表

支持的 grant_types：

授权类型	说明
authorization_code	授权码模式
refresh_token	刷新令牌
client_credentials	客户端凭证模式（仅 MachineToMachine）

请求示例：

curl -X POST https://your-domain/api/v1/applications \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Web App",
    "type": "Traditional",
    "description": "Main web application",
    "oidc_client_metadata": {
      "redirect_uris": [
        "https://app.example.com/callback",
        "http://localhost:3000/callback"
      ],
      "grant_types": [
        "authorization_code",
        "refresh_token"
      ]
    }
  }'

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "app_002",
    "name": "My Web App",
    "type": "Traditional",
    "description": "Main web application",
    "client_id": "cbc_app_x7k9m2n4p1",
    "client_secret": "cbc_secret_a1b2c3d4e5f6g7h8i9j0",
    "oidc_client_metadata": {
      "redirect_uris": [
        "https://app.example.com/callback",
        "http://localhost:3000/callback"
      ],
      "grant_types": [
        "authorization_code",
        "refresh_token"
      ]
    },
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T08:00:00Z"
  }
}

---

获取应用详情

GET /api/v1/applications/:id

根据应用 ID 获取应用详细信息。

路径参数：

参数	类型	说明
id	string	应用 ID

请求示例：

curl -X GET https://your-domain/api/v1/applications/app_002 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "app_002",
    "name": "My Web App",
    "type": "Traditional",
    "description": "Main web application",
    "client_id": "cbc_app_x7k9m2n4p1",
    "oidc_client_metadata": {
      "redirect_uris": [
        "https://app.example.com/callback",
        "http://localhost:3000/callback"
      ],
      "grant_types": [
        "authorization_code",
        "refresh_token"
      ]
    },
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T08:00:00Z"
  }
}

---

更新应用

PATCH /api/v1/applications/:id

更新应用信息。仅传入需要修改的字段。

路径参数：

参数	类型	说明
id	string	应用 ID

请求体：

字段	类型	必填	说明
name	string	否	应用名称
description	string	否	应用描述
oidc_client_metadata	object	否	OIDC 客户端配置
oidc_client_metadata.redirect_uris	string[]	否	授权回调地址列表
oidc_client_metadata.grant_types	string[]	否	授权类型列表

请求示例：

curl -X PATCH https://your-domain/api/v1/applications/app_002 \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Web App v2",
    "oidc_client_metadata": {
      "redirect_uris": [
        "https://app-v2.example.com/callback"
      ]
    }
  }'

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "app_002",
    "name": "My Web App v2",
    "type": "Traditional",
    "description": "Main web application",
    "client_id": "cbc_app_x7k9m2n4p1",
    "oidc_client_metadata": {
      "redirect_uris": [
        "https://app-v2.example.com/callback"
      ],
      "grant_types": [
        "authorization_code",
        "refresh_token"
      ]
    },
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T12:00:00Z"
  }
}

---

删除应用

DELETE /api/v1/applications/:id

删除指定应用。删除后该应用的 client_id 和 client_secret 将立即失效。

路径参数：

参数	类型	说明
id	string	应用 ID

请求示例：

curl -X DELETE https://your-domain/api/v1/applications/app_002 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": null
}

---

轮换客户端密钥

POST /api/v1/applications/:id/secret

为指定应用生成新的客户端密钥。旧密钥将立即失效。

注意： 新的 client_secret 仅在此响应中返回一次，请妥善保管。

路径参数：

参数	类型	说明
id	string	应用 ID

请求示例：

curl -X POST https://your-domain/api/v1/applications/app_002/secret \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "client_id": "app_002",
    "client_secret": "cbc_secret_new_z9y8x7w6v5u4t3s2r1q0"
  }
}

安全提示： 轮换密钥后，所有使用旧密钥的客户端将立即失去访问权限，请确保在轮换前已更新所有客户端的配置。