Organisasi

Organization adalah entitas tingkat tertinggi di Capgo. Anda bisa mengelompokkan aplikasi, anggota tim, dan resource dalam satu wadah. Setiap organization dapat memiliki banyak anggota dengan role dan permission yang berbeda.

Use Case Umum

• Membuat organisasi baru untuk perusahaan Anda
• Mengelola pengaturan organisasi
• Memperbarui informasi organisasi
• Mengambil detail organisasi

Endpoints

GET

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

Mengambil informasi organisasi. Jika orgId disediakan dalam parameter, akan mengembalikan satu organisasi. Jika tidak, akan mengembalikan semua organisasi yang dapat diakses.

Parameter Query

• orgId (opsional): ID organisasi spesifik yang ingin diambil

Tipe Respons

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
}

Contoh Request

# 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

Contoh Respons

{
  "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/

Membuat organisasi baru.

Saat menggunakan kunci API, kunci tersebut harus memiliki izin org.create global dan memiliki binding organisasi saat ini org_admin atau org_super_admin binding. Ini diperlukan karena organisasi target belum ada, sehingga RBAC berbasis scope org belum bisa diperiksa.

Jika request berhasil, Capgo akan otomatis memberikan kunci API yang sama org_super_admin pada organisasi baru tersebut.

Catatan

org.create tidak diberikan ke kunci API baru secara default. Aktifkan Izinkan pembuatan organisasi di form kunci API, atau sertakan "global_permissions": ["org.create"] saat membuat kunci melalui API.

Body Request

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

Contoh Request

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/

Contoh Response

{
  "id": "org_456"
}

Kesalahan Izin

Jika kunci API tidak memiliki org.create, API mengembalikan 403:

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

PUT

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

Memperbarui organisasi yang ada. Memerlukan role admin pada organisasi target.

Body Request

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

Contoh Request

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/

Contoh Response

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

DELETE

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

Hapus organisasi yang sudah ada. Memerlukan izin delete pada organisasi target, biasanya melalui org_super_admin role. Tindakan ini tidak dapat dibatalkan dan akan menghapus semua apps, bundles (versi), dan resource terkait.

Skill org.create Izin global tidak mengizinkan penghapusan organisasi.

Parameter Query

• orgId: ID organisasi yang akan dihapus

Contoh Request

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

Contoh Response

{
  "status": "ok"
}

Penanganan Error

Semua error menggunakan format error standar yang dijelaskan dalam ikhtisar API.

Skenario error umum dan responsnya:

// 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": {}
}

Praktik Terbaik

1. Penamaan: Gunakan nama yang jelas dan deskriptif untuk organisasi
2. Role: Berikan role yang sesuai kepada anggota tim
3. Email: Gunakan email grup untuk management_email guna menghindari masalah jika email pribadi berubah
4. Logo: Host logo di CDN yang andal dan gunakan URL HTTPS

Lanjutkan dari Organizations

Jika Anda menggunakan Organisasi untuk merencanakan operasi dashboard dan API, hubungkan dengan Ikhtisar API untuk detail implementasi di Ringkasan API, Pendahuluan untuk detail implementasi di Pendahuluan, Kunci API untuk detail implementasi pada API Keys, Perangkat untuk detail implementasi pada Devices, dan Bundle untuk detail implementasi pada Bundles.