组织

Organization 是 Capgo 中的顶层实体。你可以通过 Organization 将应用、团队成员和资源集中管理。每个 Organization 都可以有多个成员，并为他们分配不同的角色和权限。

常见用例

• 为您的公司创建新组织
• 管理组织设置
• 更新组织信息
• 获取组织详情

端点

GET

https://api.capgo.app/organization/

获取组织信息。如果 orgId 在参数中提供，则返回单个组织。否则，返回所有可访问的组织。

查询参数

• orgId (可选): 要检索的特定组织 ID

响应类型

interface Organization {
  id: string
  created_by: string
  created_at: string
  updated_at: string
  logo: string | null
  name: string
  management_email: string
  customer_id: string | null
}

请求示例

# Get all organizations
curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/organization/

# Get specific organization
curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/organization/?orgId=org_123

响应示例

{
  "data": {
    "id": "org_123",
    "name": "My Company",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "logo": "https://example.com/logo.png",
    "management_email": "admin@example.com",
    "customer_id": "cus_123"
  }
}

POST

https://api.capgo.app/organization/

创建一个新组织。

使用 API 密钥时，该密钥必须具备全局 org.create 权限以及当前有效的组织范围 org_admin 或 org_super_admin 绑定。这是因为目标组织尚不存在，因此无法按常规的组织级 RBAC 对其进行校验。

请求成功后，Capgo 会自动将相同的 API 密钥分配 org_super_admin 到新组织上。

注意

org.create 默认情况下，新的 API 密钥不会获得该权限。请在 “允许创建组织” API 密钥表单中启用，或在 "global_permissions": ["org.create"] 通过 API 创建密钥时包含该权限。

请求体

interface OrganizationCreate {
  name: string
  email?: string
  estimatedMau?: number
  website?: string
}

请求示例

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Organization",
    "email": "admin@example.com",
    "website": "https://example.com"
  }' \
  https://api.capgo.app/organization/

响应示例

{
  "id": "org_456"
}

权限错误

如果 API 密钥没有 org.create，API 会返回 403:

{
  "error": "permission_denied",
  "message": "Permission denied: org.create",
  "moreInfo": {}
}

PUT

https://api.capgo.app/organization/

更新现有组织。需要对目标组织拥有 admin 角色。

请求体

interface OrganizationUpdate {
  orgId: string
  logo?: string
  name?: string
  management_email?: string
}

请求示例

curl -X PUT \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "org_123",
    "name": "New Company Name",
    "management_email": "newemail@example.com"
  }' \
  https://api.capgo.app/organization/

响应示例

{
  "status": "Organization updated",
  "data": {
    "id": "org_123",
    "name": "New Company Name",
    "management_email": "newemail@example.com"
  }
}

删除

https://api.capgo.app/organization/

删除现有组织。需要目标组织的删除权限，通常通过 org_super_admin 角色获取。此操作不可逆，并将移除所有关联的 App、bundle (版本) 及资源。

本指南中介绍的 org.create 全局权限不允许删除组织。

查询参数

• orgId: 要删除的组织 ID

请求示例

curl -X DELETE \
  -H "x-api-key: YOUR_API_KEY" \
  https://api.capgo.app/organization/?orgId=org_123

响应示例

{
  "status": "ok"
}

错误处理

所有错误均采用以下文档中描述的标准错误格式： API 概览.

常见的错误场景及其响应：

// Missing or invalid API key (HTTP 401)
{
  "error": "invalid_apikey",
  "message": "Invalid apikey",
  "moreInfo": {}
}

// The API key has no access to the requested organization
{
  "error": "invalid_org_id",
  "message": "You can't access this organization",
  "moreInfo": { "org_id": "046a36ac-e03c-4590-9257-bd6c9dba9ee8" }
}

// The organization requires API keys with an expiration date (HTTP 401)
{
  "error": "org_requires_expiring_key",
  "message": "This organization requires API keys with an expiration date. Please use a different key or update this key with an expiration date.",
  "moreInfo": {}
}

// Creating an organization without the org.create permission (HTTP 403)
{
  "error": "permission_denied",
  "message": "Permission denied: org.create",
  "moreInfo": {}
}

// max_apikey_expiration_days out of range on update
{
  "error": "invalid_max_expiration_days",
  "message": "Maximum expiration days must be between 1 and 365",
  "moreInfo": {}
}

最佳实践

1. 命名: 为组织使用清晰且具有描述性的名称
2. 角色: 为团队成员分配适当的角色
3. 邮箱: 请使用团队邮箱作为 management_email，以避免个人邮箱变更带来的问题
4. Logo: 请将 Logo 托管在可靠的 CDN 上，并使用 HTTPS URL

继续阅读 Organizations

如果你正在使用 组织 要规划 dashboard 和 API 操作，请将其连接到 API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节， 设备 有关 Devices 的实现细节，以及 Bundle 有关 Bundles 中的实现细节。