Berechtigungen

Diese Seite zeigt, wie OpenBot entscheidet, ob ein Aufrufer etwas tun darf. Jeder Aufruf an /v1 braucht eine oder mehrere Berechtigungen. OpenBot prüft sie, bevor der Aufruf läuft.

Das Modell hat vier Teile:

Teil	Was es ist
Berechtigungsgruppe	Eine benannte Menge von Aktionen auf einer Art von Ressource, zum Beispiel `sessions.read`.
Ressourcen-Schlüssel	Der Name einer Ressource, zum Beispiel einer Session.
Policy	Sagt `allow` (erlauben) oder `deny` (verbieten) für einige Berechtigungsgruppen auf einigen Ressourcen.
Role	Eine benannte Menge von Policies, zum Beispiel Member oder Administrator. Organisationen können eigene hinzufügen.

Ein Member bekommt die Policies seiner Roles und dazu seine eigenen zusätzlichen Policies. Ein User-Token bekommt die Policies seines Members und auch seine eigenen Policies. Die Platform kann für jede Organisation deny-Policies hinzufügen. Siehe Die Reihenfolge der Prüfungen.

Berechtigungsgruppen

Liste sie mit GET /v1/organization/permission_groups auf.

ID	Ressource	Was sie erlaubt
`responses.run`	Session	Arbeit in einer Session starten, lenken (Steer), einreihen (Queue) und fortsetzen.
`sessions.read`	Session	Sessions lesen, mit ihrem Verlauf, Memory und ihren Delegationen.
`sessions.write`	Session	Sessions erstellen, ändern, forken, wiederherstellen, unterbrechen und löschen.
`requests.resolve`	Request	Die Requests deiner Agents für neue Fähigkeiten beantworten.
`agents.read`	Agent	Agents lesen, mit ihrem Memory, ihren Rules und Grants.
`agents.write`	Agent	Agents erstellen und ändern, mit ihrem Memory, ihren Rules und Grants.
`agents.delegate`	Agent	Einem Agent Arbeit geben, von einem Client oder von einem anderen Agent aus.
`triggers.read`	Trigger	Trigger lesen: ihre Zeitpläne und Webhooks.
`triggers.write`	Trigger	Trigger erstellen, ändern und löschen und ihre Webhook-Geheimnisse festlegen.
`channels.read`	Channel	Die Channels der Organisation lesen und die Personen, die mit ihnen verknüpft sind.
`channels.write`	Channel	Channels erstellen, ändern und löschen, ihre Geheimnisse festlegen und Verknüpfungen von Personen lösen.
`channels.use`	Channel	Mit dem Agent eines Channel sprechen und deine Agents dorthin schreiben lassen.
`channel_identities.read`	User	Deine verknüpften Konten auf den Plattformen von Channels lesen.
`channel_identities.write`	User	Deine Konten auf den Plattformen von Channels verknüpfen und die Verknüpfung lösen.
`connections.read`	Connection	App-Verbindungen und App-Konten lesen.
`connections.write`	Connection	App-Verbindungen erstellen, ändern und löschen, und sich bei App-Konten anmelden.
`apps.use`	Apps	Apps finden und App-Operationen und App-Ansichten nutzen.
`apps.publish`	Apps	Die Entwicklerwerkzeuge für Apps nutzen, die du veröffentlichst.
`models.use`	Model	Ein Model für eine Session wählen.
`tokens.read`	User	API-Tokens auflisten.
`tokens.write`	User	API-Tokens erstellen und widerrufen.
`organization.read`	Organization	Die Einstellungen der Organisation lesen.
`organization.write`	Organization	Die Einstellungen der Organisation ändern.
`members.read`	Organization	Members auflisten, mit ihren Roles und Policies.
`members.write`	Organization	Roles, Policies und Status von Members ändern und Members entfernen.
`roles.write`	Organization	Die eigenen Roles der Organisation erstellen, ändern und löschen.
`model_providers.read`	Organization	Die Models und Model Providers der Organisation lesen. Schlüssel werden nie gezeigt.
`model_providers.write`	Organization	Die Models, Model Providers und Schlüssel der Organisation hinzufügen, ändern und entfernen.
`sso.read`	Organization	Die E-Mail-Domains und SSO-Verbindungen lesen.
`sso.write`	Organization	E-Mail-Domains hinzufügen und bestätigen, und SSO-Verbindungen ändern.
`audit_logs.read`	Organization	Das Audit-Log lesen.
`usage.read`	Organization	Die Nutzung der Models und ihre Kosten lesen, und die Credits der Organisation.
`budgets.read`	Organization	Die Budgets lesen und wie viel davon ausgegeben ist.
`budgets.write`	Organization	Budgets erstellen, ändern und löschen.
`platform.read`	Platform	Die Platform-Einstellungen, Organisationen, Admins und gemeinsamen Models und Model Providers lesen.
`platform.write`	Platform	Die Platform-Einstellungen, Organisationen, Admins und gemeinsamen Models und Model Providers ändern.

organization.read und organization.write gelten auch für die Einstellungen der Organisation. platform.read und platform.write funktionieren nur auf der Ressource openbot.platform und nur für Platform-Admins. Siehe Platform-Gruppen.

Die API-Referenz listet die Routen auf. Der Vertrag in @openbot-build/api sagt, welche Berechtigung jede Route braucht.

Ressourcen-Schlüssel

Ein Ressourcen-Schlüssel ist ein Name aus Teilen, die durch Punkte getrennt sind:

Ressource	Schlüssel
Die Organisation	`openbot.org.<org>`
Ein Member	`openbot.org.<org>.user.<user>`
Eine Session	`openbot.org.<org>.user.<user>.session.<session>`
Ein Agent eines Members	`openbot.org.<org>.user.<user>.agent.<agent>`
Ein gemeinsamer Agent	`openbot.org.<org>.agent.<agent>`
Ein Trigger eines Members	`openbot.org.<org>.user.<user>.trigger.<trigger>`
Ein gemeinsamer Trigger	`openbot.org.<org>.trigger.<trigger>`
Ein Channel	`openbot.org.<org>.channel.<channel>`
Die Requests eines Members	`openbot.org.<org>.user.<user>.request`
Eine Verbindung	`openbot.org.<org>.user.<user>.connection.<connection>`
Die Apps eines Members	`openbot.org.<org>.user.<user>.apps`
Ein Model Provider	`openbot.org.<org>.model.<provider>`
Die ganze Platform	`openbot.platform`

Ein Agent, der einem anderen Agent gehört, hat den Schlüssel des Members oder der Organisation an der Spitze seines Besitzer-Baums. openbot.org.<org>.user.<user>.agent.<agent> ist also auch der Schlüssel eines Agents, der dem Main Agent dieses Members gehört. Wenn ein Agent einen Agent erstellt oder dauerhaft macht, braucht das Member, für das er arbeitet, agents.write an dieser Stelle.

Ein Schlüssel gilt für sich selbst und für jeden Schlüssel darunter. openbot.org.<org> gilt also für alles in der Organisation, und openbot.org.<org>.user.<user> gilt für alles eines Members.

In einer Policy kannst du zwei Platzhalter schreiben:

{org} ist die ID der Organisation.
{self} ist die User-ID des Aufrufers. Bei einem Token ist es das Member des Tokens.

Ein Punkt in einer ID wird als %2E geschrieben. So sieht er nie wie ein neuer Teil aus.

Policies

Eine Policy sieht so aus:

{
  "effect": "allow",
  "permissionGroups": ["sessions.read", "sessions.write"],
  "resources": ["openbot.org.{org}.user.{self}"]
}

OpenBot entscheidet in dieser Reihenfolge:

Wenn eine passende Policy deny sagt, ist die Antwort nein.
Wenn eine passende Policy allow sagt, ist die Antwort ja.
Wenn keine Policy passt, ist die Antwort nein.

Eine Policy passt, wenn sie die Berechtigungsgruppe nennt und eine ihrer Ressourcen den Schlüssel der Anfrage abdeckt.

Eine Policy kann nur Ressourcen in ihrer eigenen Organisation nennen. Sonst antwortet OpenBot mit 400. Nur die Policies eines Tokens können auch openbot.platform nennen.

Models begrenzen

models.use auf openbot.org.<org>.model.<provider> gilt für die Models eines Model Providers. Damit begrenzt du, welche Provider ein Member wählen darf. Diese Policy hindert ein Member daran, einen Provider zu nutzen:

{
  "effect": "deny",
  "permissionGroups": ["models.use"],
  "resources": ["openbot.org.{org}.model.prov_4c1e..."]
}

Die Reihenfolge der Prüfungen

OpenBot prüft drei Mengen von Policies, in dieser Reihenfolge:

Die Policy-Obergrenze der Platform. Sie hat nur deny-Policies, und diese gelten in jeder Organisation. Siehe Platform.
Die Member-Policies: die Policies der Roles des Members und dazu seine zusätzlichen Policies.
Die Token-Policies, wenn der Aufrufer ein User-Token nutzt.

Ein deny an irgendeiner Stelle heißt nein. Jede Menge nach der Obergrenze muss den Aufruf außerdem erlauben.

Tokens tun nie mehr als ihr Member

Ein User-Token hat zwei Mengen von Policies: die Policies seines Members und seine eigenen Policies. Beide Mengen müssen ja sagen. Ein Token kann also weniger tun als sein Member, aber nie mehr. Wenn ein Administrator dem Member eine Role wegnimmt, verliert auch jedes Token dieses Members sie.

Ein Token, das ohne policies erstellt wurde, bekommt diese Policy. Sie erlaubt alles in der Organisation, außer Tokens zu verwalten. Sie enthält nie platform.read oder platform.write:

{
  "effect": "allow",
  "permissionGroups": [
    "responses.run",
    "sessions.read",
    "...",
    "audit_logs.read"
  ],
  "resources": ["openbot.org.{org}"]
}

Dieses Beispiel erstellt ein Token, das nur deine Sessions lesen kann:

curl -b cookies.txt \
  -H "Origin: https://api.example.com" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dashboard","policies":[{"effect":"allow","permissionGroups":["sessions.read"],"resources":["openbot.org.{org}.user.{self}"]}]}' \
  https://api.example.com/v1/user/tokens

Roles

Liste sie mit GET /v1/organization/roles auf. Die Liste enthält die eingebauten Roles und die eigenen Roles der Organisation. Jede Role hat builtin: true oder builtin: false.

Eingebaute Roles

Jede Organisation hat diese Roles. Sie lassen sich nicht ändern. Eine Änderung ergibt 409 mit RoleReadOnly.

Role	Was sie kann
`super_administrator`	Alles in der Organisation. Nur ein Super Administrator kann diese Role geben oder wegnehmen.
`administrator`	Die Organisation, ihre Members, ihre gemeinsamen Agents, ihre gemeinsamen Trigger und ihre Channels verwalten und das Audit-Log lesen. Nur mit den eigenen Sessions und Verbindungen arbeiten.
`administrator_read_only`	Die Organisation, ihre Members, die Nutzung, die Budgets und das Audit-Log lesen und die gemeinsamen Agents, Trigger und Channels nutzen. Nur mit den eigenen Sessions und Verbindungen arbeiten.
`member`	Mit den eigenen Agents, Sessions, Triggern, Verbindungen und Tokens arbeiten, die gemeinsamen Agents, Trigger, Channels und Models der Organisation nutzen und ihre Einstellungen lesen.
`auditor`	Die Organisation, ihre Members, die Nutzung, die Budgets und das Audit-Log lesen. Sonst nichts.

Einige eingebaute Roles haben auch die Gruppen für Roles, Model Providers, SSO, Channels, Nutzung und Budgets:

Role	Zusätzliche Gruppen für Funktionen der Organisation
`super_administrator`	Jede Berechtigungsgruppe, außer `platform.read` und `platform.write`.
`administrator`	`roles.write`, `model_providers.read`, `model_providers.write`, `sso.read`, `sso.write`, `channels.read`, `channels.write`, `usage.read`, `budgets.read`, `budgets.write`.
`administrator_read_only`	`model_providers.read`, `sso.read`, `channels.read`, `usage.read`, `budgets.read`.
`auditor`	`usage.read`, `budgets.read`.

Um einem Member weniger zu geben als eine Role, füge dem Member eine deny-Policy hinzu. Dieses Beispiel hindert ein Member daran, Arbeit auszuführen. Es kann seine Sessions aber weiter lesen:

curl -X PATCH -b cookies.txt \
  -H "Origin: https://api.example.com" \
  -H "Content-Type: application/json" \
  -d '{"policies":[{"effect":"deny","permissionGroups":["responses.run"],"resources":["openbot.org.{org}"]}]}' \
  https://api.example.com/v1/organization/members/u_456

Eigene Roles

Eine Organisation kann eigene Roles hinzufügen. Eine eigene Role hat einen Namen, eine Beschreibung und Policies. Ihre ID beginnt mit role_. Eigene Roles erstellen, ändern und löschen braucht roles.write.

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Reviewer","description":"Reads Sessions and answers requests.","policies":[{"effect":"allow","permissionGroups":["sessions.read","requests.resolve"],"resources":["openbot.org.{org}.user.{self}"]}]}' \
  https://api.example.com/v1/organization/roles

Route	Was sie tut
`POST /v1/organization/roles`	Erstellt eine eigene Role.
`GET /v1/organization/roles/:roleId`	Liest eine Role.
`PATCH /v1/organization/roles/:roleId`	Ändert eine eigene Role.
`DELETE /v1/organization/roles/:roleId`	Löscht eine eigene Role.

Die allow-Policies einer Role können nichts geben, was du selbst nicht tun kannst. Sonst antwortet OpenBot mit 403 und PermissionDenied.
Eine Änderung gilt sofort für jedes Member mit dieser Role.
Du kannst eine Role nicht löschen, solange ein Member oder die defaultRoles der Organisation sie nutzen. OpenBot antwortet dann mit 409 und RoleInUse.

Gib einem Member eine eigene Role mit PATCH /v1/organization/members/:userId. Siehe Organisation.

Platform-Gruppen

platform.read und platform.write sind für Platform-Admins. Sie funktionieren nur auf der Ressource openbot.platform.

Keine Role in einer Organisation gibt sie, nicht einmal super_administrator.
Eine Policy-Obergrenze oder eine Member-Policy kann sie nicht geben.
Ein User-Token eines Platform-Admins bekommt sie nur, wenn seine eigenen Policies sie auf openbot.platform nennen.

Ein Beispiel-Token findest du unter Platform.

Fehler

Status	Fehler	Wann
`403`	`PermissionDenied`	Keine Policy erlaubt den Aufruf, oder eine Policy verbietet ihn. Siehe den Body unten.
`404`	`RoleNotFound`	Die Organisation hat keine Role mit dieser ID.
`409`	`RoleReadOnly`	Du wolltest eine eingebaute Role ändern oder löschen.
`409`	`RoleInUse`	Ein Member oder die Standard-Roles nutzen die Role noch.
`503`	`AuthorizationUnavailable`	OpenBot kann die Roles und Policies des Aufrufers gerade nicht lesen.

Der Body von PermissionDenied nennt die Berechtigung und den Ressourcen-Schlüssel:

{
  "_tag": "PermissionDenied",
  "permission": "sessions.write",
  "resource": "openbot.org.org_8f3a.user.u_123.session"
}

Du erreichst nur deine eigenen Sessions und Verbindungen. Eine Session eines anderen Members antwortet mit 404, als ob es sie nicht gäbe.