조직

Capgo에서 Organization은 최상위 엔티티입니다. 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/

기존 조직을 업데이트합니다. 대상 조직에 대한 관리자 권한이 필요합니다.

요청 본문

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 키에서 기기 구현 세부 사항은 기기에서, 그리고 번들 Bundles의 구현 세부 사항은