Organisasi

Organisasi adalah entitas tingkat teratas di Capgo. Organisasi memungkinkan Anda mengelompokkan aplikasi, anggota tim, dan resource dalam satu wadah. Setiap organisasi dapat memiliki banyak anggota dengan role dan permission yang berbeda.

Kasus Penggunaan Umum

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

Endpoint

GET

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

Ambil 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 akan diambil

Tipe Response

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 Response

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

Buat organisasi baru.

Saat menggunakan kunci API, kunci tersebut harus memiliki global org.create permission dan organization-scoped yang aktif org_admin atau org_super_admin binding. Ini diperlukan karena organisasi target belum ada, sehingga RBAC berbasis org normal tidak dapat diperiksa terhadapnya.

Saat permintaan berhasil, Capgo secara otomatis menetapkan kunci API yang sama sebagai org_super_admin pada organisasi baru.

Catatan

org.create tidak diberikan secara default ke key API baru. Aktifkan Izinkan membuat organisasi di form key API, atau sertakan "global_permissions": ["org.create"] saat membuat key 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/

Perbarui organisasi yang sudah ada. Memerlukan peran admin di 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"
  }
}

HAPUS

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.

Panduan 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 di 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 organisasi yang jelas dan deskriptif
2. Peran: Berikan peran yang sesuai kepada anggota tim
3. Email: Gunakan email grup untuk management_email agar tidak ada masalah saat 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 Ringkasan API untuk detail implementasi di API Overview, Pendahuluan untuk detail implementasi di Introduction, Kunci API untuk detail implementasi di API Keys, Perangkat untuk detail implementasi di Devices, dan Bundle untuk detail implementasi di Bundles.