Management API 交互

Management API 是 Code Bird Cloud 提供的管理接口，允许你通过编程方式管理平台上的用户、应用、组织、角色等资源。通过 M2M 应用访问 Management API，可以实现自动化管理和运维操作。

什么是 Management API

Management API 提供了对 Code Bird Cloud 平台资源的完整管理能力，包括但不限于：

• 用户管理 -- 创建、查询、更新、删除用户
• 应用管理 -- 管理 OIDC/OAuth 客户端应用
• 组织管理 -- 创建和管理多租户组织结构
• 角色与权限 -- 配置角色、权限模板和资源访问控制
• API 资源 -- 注册和管理 API 资源及其 Scope

认证方式

Management API 使用 M2M（Machine-to-Machine）认证。你需要创建一个 M2M 应用，并为其分配 "Code Bird Management API access" 角色。

配置步骤

第 1 步：创建 API 资源

在管理后台创建一个 API 资源，Resource Indicator 为：

urn:codebird:management-api:{tenantID}

其中 {tenantID} 替换为你的实际租户 ID。

第 2 步：创建 M2M 应用

1. 登录 Code Bird Cloud 管理后台
2. 进入「应用管理」页面
3. 点击「创建应用」
4. 选择应用类型为 Machine-to-Machine
5. 填写应用名称（例如 "Management API Client"），点击确认
6. 记录 Client ID 和 Client Secret

第 3 步：分配 Management API 角色

为 M2M 应用分配 "Code Bird Management API access" 角色：

1. 在应用详情页面，进入「角色」标签
2. 分配 "Code Bird Management API access" 角色
3. 该角色默认包含 Scope all，表示拥有管理 API 的完整访问权限

请求令牌

使用 client_credentials 授权类型请求 Access Token：

POST /oidc/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
scope=openid

成功响应示例：

{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid"
}

令牌 Claims

通过 Management API 角色获取的 M2M 令牌，scope 字段会包含 "all"：

{
  "sub": "app_xxxxxxxx",
  "iss": "https://your-domain.com",
  "aud": ["urn:codebird:api"],
  "client_id": "app_xxxxxxxx",
  "token_type": "m2m",
  "scope": ["all"],
  "iat": 1700000000,
  "exp": 1700003600
}

调用 Management API

在请求的 Authorization Header 中携带 Bearer Token：

GET /api/v1/users
Authorization: Bearer eyJhbGciOiJFUzI1NiIs...

示例：查询用户列表

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  https://your-domain.com/api/v1/users

示例：创建应用

curl -X POST https://your-domain.com/api/v1/applications \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Web App",
    "type": "Traditional",
    "description": "A web application"
  }'

示例：查询组织列表

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  https://your-domain.com/api/v1/organizations

示例：创建组织

curl -X POST https://your-domain.com/api/v1/organizations \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "description": "Acme Corporation"
  }'

代码示例

Node.js

const OIDC_ISSUER = process.env.OIDC_ISSUER;
const CLIENT_ID = process.env.CLIENT_ID;
const CLIENT_SECRET = process.env.CLIENT_SECRET;

async function getManagementToken() {
  const response = await fetch(`${OIDC_ISSUER}/oidc/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      scope: 'openid',
    }),
  });

  if (!response.ok) {
    throw new Error('Failed to get management token');
  }

  const data = await response.json();
  return data.access_token;
}

async function listUsers() {
  const token = await getManagementToken();
  const response = await fetch(`${OIDC_ISSUER}/api/v1/users`, {
    headers: { Authorization: `Bearer ${token}` },
  });
  return response.json();
}

async function createOrganization(name, description) {
  const token = await getManagementToken();
  const response = await fetch(`${OIDC_ISSUER}/api/v1/organizations`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name, description }),
  });
  return response.json();
}

Python

import os
import requests

OIDC_ISSUER = os.environ["OIDC_ISSUER"]
CLIENT_ID = os.environ["CLIENT_ID"]
CLIENT_SECRET = os.environ["CLIENT_SECRET"]


def get_management_token() -> str:
    """Request an M2M token for Management API access."""
    response = requests.post(
        f"{OIDC_ISSUER}/oidc/token",
        data={
            "grant_type": "client_credentials",
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "scope": "openid",
        },
    )
    response.raise_for_status()
    return response.json()["access_token"]


def list_users() -> dict:
    """List all users via Management API."""
    token = get_management_token()
    response = requests.get(
        f"{OIDC_ISSUER}/api/v1/users",
        headers={"Authorization": f"Bearer {token}"},
    )
    response.raise_for_status()
    return response.json()


def create_organization(name: str, description: str) -> dict:
    """Create a new organization via Management API."""
    token = get_management_token()
    response = requests.post(
        f"{OIDC_ISSUER}/api/v1/organizations",
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
        },
        json={"name": name, "description": description},
    )
    response.raise_for_status()
    return response.json()

安全注意事项

1. 最小权限原则 -- Management API 的 all Scope 拥有完整管理权限，仅在确实需要全部权限时使用。未来版本将支持更细粒度的 Scope 控制
2. 保护凭证 -- 拥有 Management API 访问权限的 M2M 应用 Client Secret 必须严格保管
3. 审计日志 -- 定期审查通过 Management API 执行的操作
4. 网络隔离 -- 建议将调用 Management API 的服务部署在内网环境

相关文档

• M2M 认证指南 -- M2M 基础认证教程
• M2M 组织级 Token -- M2M 应用获取组织范围令牌
• 应用数据结构 -- 应用类型和配置说明
• 集成概览 -- 所有集成方式的总览