Organisationen

Organisationen sind die oberste Ebene in Capgo. Sie ermöglichen es dir, Apps, Teammitglieder und Ressourcen unter einem Dach zu bündeln. Jede Organisation kann mehrere Mitglieder mit unterschiedlichen Rollen und Berechtigungen haben.

Häufige Anwendungsfälle

• Neue Organisation für Ihr Unternehmen erstellen
• Organisationseinstellungen verwalten
• Organisationsinformationen aktualisieren
• Organisationsdetails abrufen

Endpoints

GET

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

Organisationsinformationen abrufen. Falls orgId in den Parametern angegeben ist, wird eine einzelne Organisation zurückgegeben. Andernfalls werden alle zugänglichen Organisationen zurückgegeben.

Query-Parameter

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

Response-Typ

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
}

Beispiel-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

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/

Neue Organisation erstellen.

Bei Verwendung eines API-Keys muss der Key die globale org.create Berechtigung und eine aktuelle organisationsspezifische org_admin oder org_super_admin Bindung besitzen. Dies ist erforderlich, da die Zielorganisation noch nicht existiert und daher keine reguläre org-spezifische RBAC-Prüfung durchgeführt werden kann.

Bei erfolgreichem Request weist Capgo automatisch denselben API-Key zu wie org_super_admin auf der neuen Organisation.

Hinweis

org.create wird neuen API Keys standardmäßig nicht gewährt. Aktiviere Organisationen erstellen erlauben im API Key-Formular oder füge es hinzu "global_permissions": ["org.create"] beim Erstellen des Keys über API.

Request-Body

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

Beispiel-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/

Beispielantwort

{
  "id": "org_456"
}

Berechtigungsfehler

Wenn der API-Schlüssel nicht über org.createverfügt, gibt API zurück 403:

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

PUT

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

Aktualisiert eine bestehende Organisation. Erfordert die Admin-Rolle in der Zielorganisation.

Request-Body

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

Beispiel-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/

Beispielantwort

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

LÖSCHEN

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

Löscht eine bestehende Organisation. Erfordert die Berechtigung zum Löschen in der Zielorganisation, in der Regel über die org_super_admin Rolle. Diese Aktion ist unwiderruflich und entfernt alle zugehörigen Apps, Bundles (Versionen) und Ressourcen.

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

Query-Parameter

• orgId: Die ID der zu löschenden Organisation

Beispiel-Request

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

Beispielantwort

{
  "status": "ok"
}

Fehlerbehandlung

Alle Fehler verwenden das Standardfehlerformat, das in der API Übersicht.

Häufige Fehlerszenarien und deren Antworten:

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

Best Practices

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

Weiter mit Organizations

Wenn du es nutzt Organisationen um Dashboard- und API-Operationen zu planen, verbinde es mit API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für die Implementierungsdetails in API Keys, Geräte für die Implementierungsdetails in Devices und Bundles für die Implementierungsdetails in Bundles.