組織

OrganizationはCapgoにおける最上位のエンティティです。アプリ、チームメンバー、リソースを1つの傘の下にグループ化できます。各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/

既存の組織を更新します。対象の組織の管理者ロールが必要です。

リクエストボディ

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 ロールを通じて付与されます。この操作は元に戻せません。関連するすべてのアプリ、バンドル（バージョン）、リソースが削除されます。

この 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. ロゴ：ロゴは信頼性の高い CDN にホストし、HTTPS URL を使用してください

Organizationsから続ける

使用している場合 組織 ダッシュボードと API の運用を計画するには、これを次と連携させます API の概要 「API の概要」の実装の詳細については、 はじめに 「はじめに」における実装の詳細については、 API キー API Keys の実装の詳細については、 デバイス Devices の実装詳細については、および Bundle Bundlesの実装詳細については