Organisationen

Organisationen sind die obersten Ebene in Capgo. Sie ermöglichen es Ihnen, Apps, Teammitglieder und Ressourcen unter einer einzigen Dachmarke zu gruppieren. Jede Organisation kann mehrere Mitglieder mit unterschiedlichen Rollen und Berechtigungen haben.

Gemeinsame Anwendungsfälle

• Erstellen Sie eine neue Organisation für Ihr Unternehmen
• Verwalten Sie die Organisationseinstellungen
• Aktualisieren Sie die Organisationsinformationen
• Abrufen Sie die Organisationsdetails

Endpunkte

GET

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

Rufen Sie Organisationsinformationen ab. Wenn orgId Rückgabewerte alle Organisationen, wenn keine Organisation in den Parametern angegeben ist.

Abfrageparameter

• orgId (optional): Die ID der spezifischen Organisation, die abgerufen werden soll

Antworttyp

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
}

Beispielanfrage

# 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

Beispielergebnis

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

Erstellen Sie eine neue Organisation.

Wenn Sie ein API-Schlüssel verwenden, muss der Schlüssel global sein org.create Berechtigung und eine aktuelle Organisation-spezifische org_admin or org_super_admin Bindungsprozess. Dies ist erforderlich, da die Zielorganisation noch nicht existiert, sodass eine normale Organisation-spezifische RBAC-Überprüfung nicht durchgeführt werden kann.

Wenn die Anfrage erfolgreich ist, wird Capgo automatisch die gleiche API-Schlüssel zugeordnet wie org_super_admin auf der neuen Organisation.

Note

org.create wird neuen API-Schlüsseln standardmäßig nicht gewährt. Aktivieren Erstellen von Organisationen zulassen in der Form des API-Schlüssels, oder einschließen "global_permissions": ["org.create"] während der Erstellung der Schlüssel über den API.

Request Body

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

Abschnitt mit dem Titel „Beispielanfrage“

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/

Schlüsselinformationen

{
  "id": "org_456"
}

Zugriffsfehler

Wenn der Schlüssel API nicht vorhanden ist, org.createder API zurückgibt:

{
  "error": "permission_denied"
}

PUT

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

Ein bestehendes Unternehmen aktualisieren. Erfordert die Rolle Admin auf dem Zielunternehmen.

Anforderungskörper

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

Beispielanfrage

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/

Beispielantwort

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

LÖSCHEN

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

Eine bestehende Organisation löschen. Erfordert die Löscherechtigkeit auf der Zielorganisation, typischerweise über die org_super_admin Rolle. Diese Aktion ist unwiderruflich und entfernt alle zugehörigen Apps, Pakete (Versionen) und Ressourcen.

Die org.create Die globale Berechtigung erlaubt nicht das Löschen von Organisationen.

Abfrageparameter

• orgId: Die ID der Organisation, die gelöscht werden soll

Beispielanfrage

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

Beispielantwort

{
  "status": "ok"
}

Erfassung von Fehlern

Häufige Fehlerzenarien und ihre Antworten:

// Invalid API key
{
  "error": "Invalid API key",
  "status": "KO"
}

// Missing required field
{
  "error": "Name is required",
  "status": "KO"
}

// Insufficient permissions
{
  "error": "Admin role required",
  "status": "KO"
}

Gute Praktiken

1. Benennung: Verwenden Sie klare, beschreibende Namen für Organisationen
2. Rollen: Zuordnen Sie geeignete Rollen zu Teammitgliedern
3. E-Mail: Verwenden Sie eine Gruppen-E-Mail für management_email, um Probleme mit persönlichen E-Mail-Änderungen zu vermeiden
4. Logo: Hoste Logos auf einem zuverlässigen CDN und verwende HTTPS-URLs

Weitergehen von Organisationen

Wenn Sie Organisationen verwenden, um Organisationen um Dashboard und API-Operationen zu planen, verbinde es mit API-Übersicht für die Implementierungsdetails in der API-Übersicht Einführung für die Implementierungsdetails in der Einführung API-Schlüssel zur Implementierungsdetail in API Schlüsseln Geräte für die Implementierungsdetails in Devices, und Bundles zur Implementierungsdetail in Geräten und