组织管理

接口概述

组织管理接口用于创建和管理组织，包括组织成员管理、权限设置等功能。

基本信息

• 接口路径：/v1/organizations
• 需要认证：是
• 请求方式：GET/POST/PUT/DELETE
• 数据格式：JSON

API 接口

创建组织

请求

POST /v1/organizations
Authorization: Bearer your-api-key
Content-Type: application/json

{
    "name": "我的组织",
    "description": "组织描述",
    "settings": {
        "default_role": "member",
        "allow_public_projects": false
    }
}

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "id": "org_abc123",
        "name": "我的组织",
        "description": "组织描述",
        "created_at": "2024-02-01T10:00:00Z",
        "updated_at": "2024-02-01T10:00:00Z",
        "settings": {
            "default_role": "member",
            "allow_public_projects": false
        },
        "owner": {
            "id": "user_123",
            "email": "user@example.com",
            "username": "username"
        }
    }
}

获取组织列表

请求

GET /v1/organizations
Authorization: Bearer your-api-key

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "organizations": [
            {
                "id": "org_abc123",
                "name": "我的组织",
                "description": "组织描述",
                "created_at": "2024-02-01T10:00:00Z",
                "updated_at": "2024-02-01T10:00:00Z",
                "role": "owner"
            }
        ],
        "total": 1,
        "page": 1,
        "page_size": 10
    }
}

获取组织详情

请求

GET /v1/organizations/{organization_id}
Authorization: Bearer your-api-key

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "id": "org_abc123",
        "name": "我的组织",
        "description": "组织描述",
        "created_at": "2024-02-01T10:00:00Z",
        "updated_at": "2024-02-01T10:00:00Z",
        "settings": {
            "default_role": "member",
            "allow_public_projects": false
        },
        "members_count": 5,
        "projects_count": 3
    }
}

更新组织信息

请求

PUT /v1/organizations/{organization_id}
Authorization: Bearer your-api-key
Content-Type: application/json

{
    "name": "新组织名称",
    "description": "新组织描述",
    "settings": {
        "default_role": "member",
        "allow_public_projects": true
    }
}

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "id": "org_abc123",
        "name": "新组织名称",
        "description": "新组织描述",
        "updated_at": "2024-02-01T11:00:00Z",
        "settings": {
            "default_role": "member",
            "allow_public_projects": true
        }
    }
}

删除组织

请求

DELETE /v1/organizations/{organization_id}
Authorization: Bearer your-api-key

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "message": "组织已删除"
    }
}

邀请成员

请求

POST /v1/organizations/{organization_id}/invitations
Authorization: Bearer your-api-key
Content-Type: application/json

{
    "email": "newmember@example.com",
    "role": "member",
    "message": "欢迎加入我们的组织"
}

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "invitation_id": "inv_xyz789",
        "email": "newmember@example.com",
        "role": "member",
        "expires_at": "2024-02-08T10:00:00Z",
        "status": "pending"
    }
}

获取成员列表

请求

GET /v1/organizations/{organization_id}/members
Authorization: Bearer your-api-key

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "members": [
            {
                "id": "user_123",
                "email": "user@example.com",
                "username": "username",
                "role": "owner",
                "joined_at": "2024-02-01T10:00:00Z"
            }
        ],
        "total": 1,
        "page": 1,
        "page_size": 10
    }
}

更新成员角色

请求

PUT /v1/organizations/{organization_id}/members/{member_id}
Authorization: Bearer your-api-key
Content-Type: application/json

{
    "role": "admin"
}

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "id": "user_123",
        "email": "user@example.com",
        "username": "username",
        "role": "admin",
        "updated_at": "2024-02-01T11:00:00Z"
    }
}

移除成员

请求

DELETE /v1/organizations/{organization_id}/members/{member_id}
Authorization: Bearer your-api-key

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "message": "成员已移除"
    }
}

错误码

错误码	说明	解决方案
400	请求参数错误	检查请求参数是否符合要求
401	未授权	检查 API 密钥是否有效
403	权限不足	检查用户是否有相应的操作权限
404	组织不存在	检查组织 ID 是否正确
409	资源冲突	检查是否存在命名冲突等问题

权限说明

角色类型

• owner: 组织所有者
• admin: 管理员
• member: 普通成员

权限矩阵

操作	owner	admin	member
查看组织信息	✓	✓	✓
修改组织信息	✓	✓	×
删除组织	✓	×	×
邀请成员	✓	✓	×
管理成员	✓	✓	×
查看成员列表	✓	✓	✓
管理项目	✓	✓	×

使用建议

1. 组织创建

• 设置清晰的组织名称和描述
• 合理配置组织设置
• 规划成员角色和权限

2. 成员管理

• 定期审查成员权限
• 及时处理过期邀请
• 记录重要操作日志

3. 安全建议

• 定期轮换管理员
• 限制敏感操作权限
• 启用操作审计日志