Organisationen

Organisationen sind die obersten Einheiten 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.

Gängige Verwendungsfälle

• Eine neue Organisation für Ihr Unternehmen erstellen
• Organisations-Einstellungen verwalten
• Organisationsinformationen aktualisieren
• Organisationsdetails abrufen

Endpunkte

GET

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

Organisationsinformationen abrufen. Wenn __CAPGO_KEEP_0__ in den Parametern angegeben ist, wird eine einzelne Organisation zurückgegeben. Ansonsten werden alle zugänglichen Organisationen zurückgegeben. orgId Abfrageparameter

Abschnitt mit dem Titel “Abfrageparameter”

• orgId Antworttyp

Abschnitt mit dem Titel “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
}

Abschnitt mit dem Titel “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

Beispielantwort

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

Eine neue Organisation erstellen.

Wenn Sie bei der Verwendung eines API-Schlüssels sicherstellen möchten, dass der Schlüssel die globale org.create Berechtigung und eine aktuelle Organisation-scope org_admin oder org_super_admin Bindung hat. Dies ist erforderlich, weil die Zielorganisation noch nicht existiert, daher kann die normale Organisation-scope RBAC nicht gegen sie überprüft werden.

Wenn die Anfrage erfolgreich ist, Capgo stellt API automatisch als denselben Schlüssel ein. org_super_admin On der neuen Organisation.

Anmerkung

org.create Dieses Recht wird neuen API Schlüsseln standardmäßig nicht gewährt. Aktivieren Sie Erstellen von Organisationen zulassen im Schlüsselform von API, oder "global_permissions": ["org.create"] beim Erstellen des Schlüssels über API.

Anfragekörper

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

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/

Beispielantwort

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

Eine bestehende Organisation aktualisieren. Erfordert die Rolle Admin auf der Zielorganisation.

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/

Beispielsantwort

{
  "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ösch-Rechte auf die Zielorganisation, typischerweise über die Rolle. Diese Aktion ist unwiderruflich und entfernt alle zugehörigen Apps, Pakete (Versionen) und Ressourcen. org_super_admin Die globale Berechtigung ermöglicht nicht das Löschen von Organisationen.

Abfrageparameter org.create Abschnitt mit dem Titel “Abfrageparameter”

Die ID der Organisation, die gelöscht werden soll

• orgIdAbschnitt mit dem Titel “Beispielanfrage”

Terminalfenster

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

Beispiel-Antwort

{
  "status": "ok"
}

Fehlerbehandlung

Häufige Fehlerfälle 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. NamenVerwenden Sie klare, beschreibende Namen für Organisationen
2. Rollen: Rollen den Teammitgliedern zuweisen
3. E-Mail: Verwende 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

Fortsetzen von Organisationen

Wenn Sie "Organizations" verwenden Organisationen um das Dashboard und API-Operationen zu planen, verbinden Sie es mit API-Übersicht um die Implementierungsdetails in der API-Übersicht zu sehen, Einführung für die Implementierungsdetails in Einführung, API Schlüssel für die Implementierungsdetails in API Schlüssel, Geräte für die Implementierungsdetails in Geräte, und Pakete für die Implementierungsdetails in Pakete.