Access-Control-Referenz

Capgo nutzt rollenbasierte Zugriffskontrolle (RBAC) um die Berechtigungen der Teammitglieder zu verwalten. Rollen sind nach dem Scope — von der gesamten Organisation bis hin zu einem einzelnen Bundle – organisiert.

Für eine visuelle Anleitung zur Mitgliederverwaltung im Dashboard siehe Organisation.

---

Rollenbereiche

Jede Rolle gehört zu einem Scope, der festlegt, auf welche Ressourcen der Zugriff gewährt wird.

Umfang	Gilt für	Beispiel-Anwendungsfall
Organisation	Die gesamte Organisation und alle zugehörigen Apps	Dein Co-Founder erhält Super Admin; dein Buchhalter erhält Billing Manager
App hinzu	Eine einzelne App und ihre Channels	Ein Freelancer an einer App erhält die Rolle App Developer
Channel	Ein einzelner Channel innerhalb einer App	Ein QA-Engineer verwaltet nur den staging Channel
Bundle	Eine einzelne Bundle-Version	Ein Reviewer benötigt Lesezugriff auf ein bestimmtes Release

Ein Mitglied kann pro Scope-Ziel eine Rolle innehaben — z. B. eine Org-Rolle, eine Rolle für App A und eine andere für App B.

---

Organisationsrollen

Diese Rollen werden beim Einladen eines Members zugewiesen. Sie gewähren Zugriff auf die gesamte Organisation.

Rolle	Interner Name	Beschreibung
Super Admin	org_super_admin	Entspricht dem Owner. Volle Kontrolle, inklusive Löschen der Org, Verwalten der Abrechnung und Übertragen von Apps. Wird dem Org-Ersteller automatisch zugewiesen.
Admin	org_admin	Vollständige Administration — Mitglieder, Apps und Channels verwalten. Kann die Organisation nicht löschen, Abrechnungen nicht ändern, Apps nicht übertragen oder Nutzer zu Super Admins befördern.
Billing Manager	org_billing_admin	Reiner Billing-Zugriff: Abrechnungsinfos, Rechnungen und Billing Audit Logs einsehen und aktualisieren. Kein Zugriff auf Apps oder Mitglieder.
Mitglied	org_member	Schreibgeschützter Zugriff auf die Orga und alle zugehörigen Apps.

Berechtigungsmatrix der Organisation

Berechtigung	Beschreibung	Super-Admin	Admin	Billing Manager	Mitglied
org.read	Organisation anzeigen	✅	✅	✅	✅
org.update_settings	Orga-Name, Logo und Management-E-Mail bearbeiten	✅	✅	❌	❌
org.delete	Organisation dauerhaft löschen	✅	❌	❌	❌
org.read_members	Mitgliederliste anzeigen	✅	✅	❌	✅
org.invite_user	Neue Mitglieder einladen	✅	✅	❌	❌
org.update_user_roles	Mitgliederrollen ändern (Admins können keine Super Admins ernennen — durch Rollenhierarchie gesperrt)	✅	✅	❌	❌
org.read_billing	Abrechnungsdaten und aktuellen Plan einsehen	✅	✅	✅	❌
org.update_billing	Zahlungsmethode und Plan aktualisieren	✅	❌	✅	❌
org.read_invoices	Rechnungen anzeigen	✅	✅	✅	❌
org.read_audit	Aktivitätsprotokoll der Organisation einsehen	✅	✅	❌	❌
org.read_billing_audit	Abrechnungsrelevantes Audit-Log anzeigen	✅	✅	✅	❌

Hinweis

Organisationsrollen erben alle Berechtigungen der darunterliegenden App-, Channel- und Bundle-Rollen in der Hierarchie. Eine Super Admin kann alles, was ein App-Admin oder Channel-Admin kann – in allen Apps und Channels.

---

App-Rollen

Beschränkt auf eine einzelne App. Nutze diese, wenn ein Teammitglied nur an einer App und nicht an der gesamten Organisation arbeiten soll.

Rolle	Interner Name	Beschreibung
App-Admin	app_admin	Volle Kontrolle über eine App – Channels, Geräte und Benutzerrollen für die App. Die App kann nicht gelöscht oder übertragen werden (dies sind Org-Level-Operationen).
App-Entwickler	app_developer	Bundles hochladen, Geräte verwalten, Native Builds triggern, Channel-Einstellungen aktualisieren. Keine Löschungen, keine Änderungen an App-Einstellungen, keine Channel-Erstellung.
App-Uploader	app_uploader	Lesezugriff + neue Bundle-Versionen hochladen.
App-Reader	app_reader	Nur Lesezugriff – Stats, Bundles, Channels, Logs, Geräte.
App-Vorschau	app_preview	Org- und App-gebundener Preview CI Lifecycle: Ein Bundle hochladen und einen Preview-Channel erstellen. Das Erstellen des Channels gewährt automatisch Lifecycle-Rechte nur für diesen.

App-Berechtigungsmatrix

Berechtigung	Beschreibung	App-Admin	App-Entwickler	App-Uploader	App-Reader
app.read	App-Details, Stats und Metadaten einsehen	✅	✅	✅	✅
app.update_settings	App-Einstellungen bearbeiten	✅	❌	❌	❌
app.read_bundles	Liste der hochgeladenen Bundles anzeigen	✅	✅	✅	✅
app.upload_bundle	Neue Bundle-Version hochladen	✅	✅	✅	❌
app.create_channel	Neuen Channel erstellen	✅	❌	❌	❌
app.read_channels	Channels anzeigen	✅	✅	✅	✅
app.read_logs	Update-Delivery-Logs anzeigen	✅	✅	✅	✅
app.manage_devices	Geräte zuweisen, überschreiben oder entkoppeln	✅	✅	❌	❌
app.read_devices	Geräteliste anzeigen	✅	✅	✅	✅
app.build_native	Native Cloud Build auslösen	✅	✅	❌	❌
app.read_audit	Aktivitätsprotokoll auf App-Ebene anzeigen	✅	✅	✅	✅
app.update_user_roles	App-spezifische Rollenzuweisungen verwalten	✅	❌	❌	❌
bundle.delete	Bundle löschen	✅	❌	❌	❌

Hinweis

app.delete und app.transfer sind Operationen auf Org-Ebene — nur org_super_admin kann diese ausführen, unabhängig von Rollen auf App-Ebene.

Berechtigungssatz für App Preview

Nutzt App-Vorschau (app_preview) für einen organisations- und app-gebundenen CI-Key, der den PR-Preview-Lifecycle verwaltet, ohne weitreichenden Zugriff auf die App oder die gesamte Organisation zu haben.

Der app_preview Diese Bindung gewährt nur diese Berechtigungen auf App-Ebene:

Berechtigung	Erlaubt
app.read	Die ausgewählte App lesen
app.read_bundles	Hochgeladene Bundles lesen
app.upload_bundle	Ein Bundle hochladen
app.create_channel	Einen Channel erstellen

Wenn ein App Preview Key einen Channel erstellt, weist Capgo diesem Key automatisch ein Child- channel_preview Binding nur für den neuen Channel zu:

Berechtigung	Erlaubt
channel.read	Den vom Key erstellten Channel lesen
channel.promote_bundle	Das eigene hochgeladene Bundle des Keys auf diesem Channel setzen
channel.delete	Diesen Channel löschen

Da app_preview behält app.read, kann die Channel-Metadaten in der ausgewählten App auflisten. Das automatische Child-Binding ist eine Management- Grenze: Es gewährt keine Lifecycle-Mutationen für Channels, die der Key nicht selbst erstellt hat.

Capgo speichert den Preview-Key, der den jeweiligen Channel erstellt und das Bundle hochgeladen hat. Daher kann ein App Preview Key alle benötigten nicht-öffentlichen Preview-Channels erstellen, sein eigenes Bundle promoten und diesen Channel sowie das Bundle atomar mit channel delete --delete-bundlelöschen; dies ist nicht für bestehende Default-/Main-Channels, Channels anderer Preview-Keys oder Bundles anderer Keys möglich.

Es umfasst kein app.update_settings, Device- oder Rollen-Management, channel.update_settings, channel.rollback_bundle, Forced-Device-Management oder generisches bundle.delete.

Achtung

Jedes App Preview Binding bleibt mit der Inhaber-Organisation der ausgewählten App verknüpft. Die Rolle ist keine organisationsweite Rolle; sie entfernt die Organisationszugehörigkeit nicht. Das Entziehen oder das Ablaufen des App Bindings entfernt den effektiven Lifecycle-Zugriff des Keys.

---

Channel-Rollen

Beschränkt auf einen einzelnen Channel. Ideal, um gezielten Zugriff auf einen bestimmten Release-Channel zu gewähren.

Hinweis

Channel-Rollen sind derzeit verfügbar allerdings nur über API und CLI – es gibt keine UI, um sie im Dashboard zuzuweisen. channel_preview ist eine Ausnahme: Capgo erstellt sie automatisch für einen App Preview-Key, wenn dieser einen Channel erstellt. Nutze im Dashboard Channel-Permission-Overrides stattdessen, um den Channel-Zugriff pro Nutzer fein abzustimmen.

Rolle	Interner Name	Beschreibung
Channel-Admin	channel_admin	Volle Kontrolle über einen Channel: Einstellungen, Bundles promoten/zurückrollen, Forced Devices verwalten.
Channel-Betrachter	channel_reader	Read-only — aktuelles Bundle, Historie, Forced Devices, Audit-Log.
Channel-Vorschau	channel_preview	Vom System dem App Preview Key zugewiesen, der den Channel erstellt hat: Lesen, eigenes Bundle promoten und den Channel löschen.

Channel-Berechtigungsmatrix

Berechtigung	Beschreibung	Channel-Admin	Channel-Betrachter	Channel-Vorschau
channel.read	Channel und das aktuelle Bundle anzeigen	✅	✅	✅
channel.update_settings	Kanaleinstellungen bearbeiten (Plattform-Toggles, Update-Policy…)	✅	❌	❌
channel.delete	Kanal löschen	✅	❌	✅
channel.read_history	Bundle-Zuweisungshistorie anzeigen	✅	✅	❌
channel.promote_bundle	Aktives Bundle im Kanal festlegen	✅	❌	✅
channel.rollback_bundle	Auf ein vorheriges Bundle zurückrollen	✅	❌	❌
channel.manage_forced_devices	Bestimmte Geräte auf diesen Kanal erzwingen	✅	❌	❌
channel.read_forced_devices	Liste der erzwungenen Geräte anzeigen	✅	✅	❌
channel.read_audit	Kanal-Aktivitätsprotokoll anzeigen	✅	✅	❌

---

Bundle-Rollen

Beschränkt auf eine einzelne Bundle-Version. Selten benötigt – die meisten Teams nutzen stattdessen Rollen auf App-Ebene.

Hinweis

Bundle-Rollen sind derzeit verfügbar, allerdings nur über API und CLI – es gibt keine UI, um sie im Dashboard zuzuweisen.

Rolle	Interner Name	Beschreibung
Bundle-Admin	bundle_admin	Ein bestimmtes Bundle lesen, Metadaten aktualisieren und löschen.
Bundle-Viewer	bundle_reader	Schreibgeschützter Zugriff auf ein bestimmtes Bundle.

---

Channel-Permission-Overrides (Dashboard)

Im Dashboard wird der Channel-Zugriff standardmäßig durch die App-Rolle des Nutzers bestimmt. Für eine feinere Kontrolle kannst du spezifische Channel-Berechtigungen überschreiben, pro Nutzer oder Gruppe, ohne deren App-Rolle zu ändern.

Overrides werden im Tab der App Auskunft konfiguriert, indem du auf den Button für Channel-Berechtigungen (Schild-Icon) neben einem Nutzer klickst. Siehe Organisation — Channel-Berechtigungen überschreiben für eine visuelle Anleitung.

Überschreibbare Berechtigungen

Berechtigung	Beschreibung	Standardverhalten
Lies	Channel und das aktuelle Bundle anzeigen	Von der App-Rolle geerbt
Verlauf	Verlauf der Bundle-Zuweisungen anzeigen	Von der App-Rolle geerbt
Bundle zuordnen	Das aktive Bundle auf dem Channel festlegen oder ändern	Von der App-Rolle geerbt

Jede Berechtigung kann so eingestellt werden:

• Standard — Vererbung aus der App-Rolle (Standard)
• Zulassen — Explizite Erteilung, unabhängig von der App-Rolle
• Verweigern — Explizites Blockieren, unabhängig von der App-Rolle

So können Sie beispielsweise einem App Reader die Berechtigung geben, Bundles mit der staging Channel zu verknüpfen, ohne ihn zum App Developer zu machen.

---

Rollenhierarchie

Rollen bilden eine Hierarchie. Eine übergeordnete Rolle erbt alle Berechtigungen ihrer untergeordneten Rollen. Das bedeutet, dass ein org_admin kann alles, was ein app_admin alles tun kann, was wiederum ein channel_admin tun kann, und so weiter.

Super Admin (org_super_admin)
  └── Admin (org_admin)
        └── App Admin (app_admin)
              ├── App Developer (app_developer)
              │     └── App Uploader (app_uploader)
              │           └── App Reader (app_reader)
              ├── Bundle Admin (bundle_admin)
              │     └── Bundle Viewer (bundle_reader)
              └── Channel Admin (channel_admin)
                    └── Channel Viewer (channel_reader)

So funktioniert es in der Praxis:

• Ein Admin auf Org-Ebene alles tun kann, was ein App-Admin kann, für jede App in der Orga.
• Ein App-Admin für eine bestimmte App alles, was ein Channel-Admin kann, für jeden Channel in dieser App.
• Ein App-Entwickler kann alles, was ein App-Uploader kann, plus weitere Funktionen.

Die Hierarchie verläuft nur abwärts — ein channel_admin erhält niemals Berechtigungen auf Org-Ebene, selbst wenn er eine Rolle auf App-Ebene besitzt.

---

Gruppen

Anstatt Rollen jedem Nutzer einzeln zuzuweisen, kannst du Groups erstellen und Rollen der Gruppe zuweisen. Jedes Mitglied der Gruppe erbt diese Rollen automatisch.

Funktionsweise von Groups

• Eine Gruppe gehört zu eine Organisation — sie kann nicht mehrere Orgs umfassen.
• Gruppen können Rollenbindungen auf jeder Ebene: Org, App, Channel oder Bundle. Beispielsweise kann einer Gruppe die App-Entwickler Rolle für App A und die Channel-Admin Rolle für den staging Channel von App B.
• Bei der Prüfung der Berechtigungen eines Benutzers werden alle Gruppenmitgliedschaften transparent aufgelöst. Wenn eine seiner Gruppen die erforderliche Berechtigung gewährt, wird der Zugriff freigegeben.
• Ein Benutzer kann zu mehrere Gruppen, und die Berechtigungen aller Gruppen sind additiv.
• Gruppenbasierte Berechtigungen gelten nur für User-Principals — API Keys erben keine Gruppenrollen.

Wann Gruppen sinnvoll sind

Szenario	Ohne Gruppen	Mit Gruppen
5 QA-Engineers benötigen Developer-Zugriff auf 3 Apps	15 einzelne Role-Bindings	1 Gruppe + 3 Rollen-Bindings
Jemand tritt dem QA-Team bei	3 Rollen-Bindings manuell hinzufügen	Sie der Gruppe hinzufügen
Jemand verlässt das QA-Team	3 Rollen-Bindings manuell entfernen	Sie aus der Gruppe entfernen

Gruppenverwaltung via API

Alle Gruppen-Endpoints erfordern Authentifizierung und werden unter bereitgestellt /private/groups.

Gruppen auflisten

curl -X GET "https://api.capgo.app/private/groups/<ORG_ID>" \
  -H "authorization: <API_KEY>"

Erfordert org.read_members Berechtigung.

Gruppe erstellen

curl -X POST "https://api.capgo.app/private/groups/<ORG_ID>" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "QA Team",
    "description": "Quality assurance engineers"
  }'

Erfordert org.update_user_roles Berechtigung (Super-Admin oder Admin).

Gruppe aktualisieren

curl -X PUT "https://api.capgo.app/private/groups/<GROUP_ID>" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "QA Team",
    "description": "Updated description"
  }'

Gruppe löschen

curl -X DELETE "https://api.capgo.app/private/groups/<GROUP_ID>" \
  -H "authorization: <API_KEY>"

Beim Löschen einer Gruppe werden auch alle zugehörigen Role Bindings entfernt. Mitglieder werden nicht aus der Organisation gelöscht.

Gruppenmitglieder auflisten

curl -X GET "https://api.capgo.app/private/groups/<GROUP_ID>/members" \
  -H "authorization: <API_KEY>"

Mitglied zu einer Gruppe hinzufügen

curl -X POST "https://api.capgo.app/private/groups/<GROUP_ID>/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "<USER_UUID>" }'

Der Nutzer muss bereits Mitglied der Organisation sein. Das Hinzufügen eines bereits vorhandenen Mitglieds hat keine Auswirkung.

Mitglied aus einer Gruppe entfernen

curl -X DELETE "https://api.capgo.app/private/groups/<GROUP_ID>/members/<USER_UUID>" \
  -H "authorization: <API_KEY>"

Hinweis

Um einer Gruppe eine Rolle zuzuweisen, nutzen Sie die Role Bindings API mit principal_type: "group" und principal_id der Gruppen-UUID.

---

Rollen zuweisen via API

Mitglieder auflisten

curl -X GET "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "orgId": "<ORG_ID>" }'

Antwort:

[
  {
    "uid": "user-uuid",
    "email": "alice@example.com",
    "image_url": "https://...",
    "role": "org_admin",
    "is_tmp": false
  }
]

Mitglied einladen

curl -X POST "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "<ORG_ID>",
    "email": "bob@example.com",
    "invite_type": "org_admin"
  }'

Zulässige Werte für invite_type:

Wert	Zugewiesene Rolle
org_super_admin	Super-Admin
org_admin	Admin
org_billing_admin	Billing Manager
org_member	Mitglied

Mitglied entfernen

curl -X DELETE "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "<ORG_ID>",
    "email": "bob@example.com"
  }'

---

Rollen zuweisen über CLI

Organisationen auflisten

npx @capgo/cli organization list --apikey <API_KEY>

Mitglieder auflisten

npx @capgo/cli organization members <ORG_ID> --apikey <API_KEY>

Hinweis

CLI unterstützt derzeit nur das Auflisten von Mitgliedern. Um Mitglieder einzuladen oder Rollen programmatisch zu ändern, nutze die API Endpoints oben.

---

Benutzerdefinierte Rollen

Die Standardrollen decken die meisten Teamstrukturen ab. Die Erstellung benutzerdefinierter Rollen ist auf unserer Roadmap – falls dein Team dies benötigt, kontaktiere uns. Dein Anwendungsfall hilft uns direkt dabei, dieses Feature zu priorisieren.

Weiterlesen im Access Control Reference

Wenn du es nutzt Access-Control-Referenz 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.