Organisation

Für die Organisationsverwaltung. Jede Aufgabe braucht die genannten Rechte. Nur Plattform-Admins ändern Einstellungen unter /v1/platform. Beginne mit dem Administrationshandbuch.

Diese Seite zeigt, wie viele Menschen OpenBot gemeinsam nutzen. Eine Organization (Organisation) ist eine Gruppe von Menschen, die Bots, Models und Einstellungen teilen. Eine Platform hat viele Organisationen. Ein User und eine Organisation sind zwei verschiedene Dinge. Ein User kann Organisationen erstellen, auch eine nur für sich selbst, und kann Member (Mitglied) in vielen Organisationen sein.

Die Routen der aktuellen Organisation liegen unter /v1/organization. Sie nehmen ein User-Token oder das Session-Cookie an. Mit dem Cookie sendest du den Header OpenBot-Organization, wenn du zu mehr als einer Organisation gehörst. Siehe Authentifizierung.

Wer beitreten kann

Jedes Mal, wenn sich ein Konto anmeldet, prüft OpenBot, wohin es gehört. Es prüft das auch bei jeder Anfrage mit dem Session-Cookie.

Weg	Role, die es bekommt	Voraussetzung
Einladung	Die Roles der Einladung	Ein Administrator hat die geprüfte E-Mail des Kontos eingeladen, und das Konto nimmt an. Siehe Einladungen.
Bestätigte Domain	Die `defaultRoles` der Organisation	Die Organisation hat die Domain der E-Mail bestätigt, `joinByDomain` ist `true`, und der Anbieter hat die E-Mail geprüft.
SSO-Verbindung	Die `defaultRoles` der Organisation	Das Konto hat sich über die SSO-Verbindung der Organisation angemeldet.
Neue Organisation	`super_administrator`	Das Konto ruft `POST /v1/organizations` auf. Siehe Eine Organisation erstellen.

OpenBot erstellt nie eine Organisation für ein neues Konto. Ein Konto ohne Organisation bekommt von Routen einer Organisation 403 mit MembershipRequired. Es kann trotzdem eine Organisation erstellen und auf Einladungen antworten.

Ältere Versionen von OpenBot haben für jedes neue Konto eine Organisation mit dem Namen “Personal” erstellt. Diese Organisationen bleiben. Sie sind normale Organisationen. Du kannst sie also umbenennen, Leute einladen oder sie verlassen. Wie du eine Domain bestätigst, steht unter SSO und Domains. Zu organizationCreation siehe Platform.

Deine Organisationen

GET /v1/organizations listet die Organisationen auf, in denen du Member bist. Ein User-Token sieht nur seine eigene Organisation.

curl -b cookies.txt https://api.example.com/v1/organizations

{
  "items": [
    {
      "id": "org_8f3a",
      "name": "Example",
      "status": "active",
      "createdAt": "2026-10-21T09:00:00.000Z"
    }
  ]
}

status ist active oder suspended. Ein Platform-Admin kann eine Organisation sperren. Dann kann niemand sie nutzen, und ihre Tokens funktionieren nicht mehr. Siehe Platform.

Eine Organisation erstellen

POST /v1/organizations erstellt eine Organisation. Du wirst ihr Super Administrator.

curl -b cookies.txt \
  -H "Origin: https://api.example.com" \
  -H "Content-Type: application/json" \
  -d '{"name":"Research"}' \
  https://api.example.com/v1/organizations

Wenn organizationCreation in den Platform-Einstellungen platform_admins ist, können das nur Platform-Admins. Andere Aufrufer bekommen 403 mit OrganizationCreationDisabled.

Eine Organisation verlassen

DELETE /v1/organizations/:organizationId/membership nimmt dich aus einer Organisation heraus. Deine Tokens für sie funktionieren sofort nicht mehr.

curl -X DELETE -b cookies.txt \
  -H "Origin: https://api.example.com" \
  https://api.example.com/v1/organizations/org_8f3a/membership

Der letzte aktive Super Administrator kann nicht gehen. OpenBot gibt 409 mit LastSuperAdministrator zurück. Gib die Role zuerst jemand anderem.
Ein User-Token kann nur seine eigene Organisation verlassen.
Wenn deine E-Mail-Domain noch bestätigt ist und joinByDomain an ist, trittst du bei der nächsten Anmeldung wieder bei.

Die Organisation lesen und ändern

GET /v1/organization liest die aktuelle Organisation. Es gibt dasselbe Objekt wie oben zurück. PATCH /v1/organization ändert ihren name. Es braucht write auf Organization.

curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Inc."}' \
  https://api.example.com/v1/organization

Einstellungen

Jede Organisation hat ihre eigenen Einstellungen. Sie liegen in der Datenbank. So nutzt jede OpenBot-Instanz dieselben Werte. GET /v1/organization/settings liest sie. Es braucht read auf Organization.

{
  "version": 2,
  "rulesModel": {
    "_tag": "Config.Selection",
    "provider": "prov_4c1e...",
    "model": "gpt-4.1-mini"
  },
  "botMemoryModel": null,
  "botMemory": true,
  "requestTimeoutMs": 86400000,
  "delegationTimeLimitMs": 3600000,
  "toolForegroundBudgetMs": 30000,
  "toolMaxDurationMs": 3600000,
  "maxBackgroundOperations": 8,
  "planApproval": {
    "approver": "chain",
    "timeoutMs": 86400000,
    "onTimeout": "stay"
  },
  "appReadRules": [],
  "defaultRoles": ["member"],
  "joinByDomain": true,
  "tokenRate": {
    "organization": null,
    "member": null,
    "bot": null,
    "token": null
  },
  "updatedAt": "2026-10-21T09:00:00.000Z"
}

Feld	Standard	Was es tut
`rulesModel`	`null`	Das Model, das Rules beurteilt. Es kann ein Language-Model oder ein Decision-Model sein. `null` heißt: Kein Model beurteilt sie. Siehe Models.
`botMemoryModel`	`null`	Das Model, das Bot-Memory lernt. `null` heißt: Bots lernen nichts.
`botMemory`	`true`	Der Memory-Bot lernt aus Chats und ergänzt die Eingabe von Turns.
`requestTimeoutMs`	24 Stunden	Wie lange ein Request auf eine Antwort wartet, bevor OpenBot ihn ablehnt. Von 1 Sekunde bis 7 Tage.
`delegationTimeLimitMs`	1 Stunde	Die Zeitgrenze von Arbeit, die keine eigene hat, wie die Arbeit eines Triggers. Von 1 Minute bis 30 Tage.
`toolForegroundBudgetMs`	30 Sekunden	Wie lange ein Tool-Aufruf in seinem Turn läuft, bevor er in den Hintergrund geht. Von 0 bis 10 Minuten. 0 schickt jeden Aufruf in den Hintergrund.
`toolMaxDurationMs`	1 Stunde	Die längste Zeit eines Tool-Aufrufs im Hintergrund. Danach stoppt er und schlägt fehl. Von 1 Sekunde bis 24 Stunden.
`maxBackgroundOperations`	8	Wie viele Tool-Aufrufe eines Chats zugleich im Hintergrund laufen dürfen. Von 0 bis 100.
`planApproval`	den Entscheider darüber fragen, nach 24 Stunden ein Plan bleiben	Wie ein Plan erlaubt wird, wenn kein Member, Bot und kein Chat es festlegt. Siehe Plan-Modus.
`appReadRules`	`[]`	App-Werkzeuge, die nur lesen: `{ cardUrl, tool }`. Siehe Requests.
`defaultRoles`	`["member"]`	Die Roles eines neuen Members.
`joinByDomain`	`true`	Menschen mit einer geprüften E-Mail in einer bestätigten Domain der Organisation treten bei, wenn sie sich anmelden.
`tokenRate`	keine Grenze	Token Rates jedes Bereichs. Wo die Platform eine kleinere Rate setzt, gilt die kleinere Rate. Siehe Token Rate.

PATCH /v1/organization/settings ändert sie. Es braucht write auf Organization. Der Body braucht expectedVersion, also die version, die du gelesen hast. Füge nur die Felder hinzu, die du ändern willst.

curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedVersion":2,"requestTimeoutMs":3600000,"joinByDomain":false}' \
  https://api.example.com/v1/organization/settings

Wenn jemand die Einstellungen nach deinem Lesen geändert hat, antwortet OpenBot mit 409, SettingsConflict und der aktuellen version. Lies sie neu und versuche es dann noch einmal.
Eine Role, die es nicht gibt, ergibt 400 mit SettingsInvalid.
Nur ein Super Administrator kann super_administrator in defaultRoles eintragen.

Jede Instanz nutzt eine Änderung sofort. Siehe Konfiguration.

Members

GET /v1/organization/members listet Members seitenweise auf. Es braucht read auf Member. Nutze limit (1 bis 100, Standard 50) und after mit dem Wert next der letzten Seite.

{
  "items": [
    {
      "userId": "u_123",
      "email": "ada@example.com",
      "name": "Ada",
      "status": "active",
      "roles": ["super_administrator"],
      "policy": "{\"_tag\":\"Rules\",\"algorithm\":\"denyOverrides\",\"rules\":[]}",
      "joinedAt": "2026-10-21T09:00:00.000Z"
    }
  ],
  "next": null
}

GET /v1/organization/members/:userId liest ein Member.

Ein Member ändern

PATCH /v1/organization/members/:userId ändert status, roles oder policy. Es braucht write auf Member.

status ist active oder suspended. Ein gesperrtes Member kann diese Organisation nicht nutzen. Seine Tokens für sie funktionieren sofort nicht mehr.
roles ist eine Liste von Role-IDs: eingebaute Roles und eigene Roles. Siehe Berechtigungen.
policy ist eine zusätzliche Policy für das Member, zusätzlich zu seinen Roles. Eine Deny-Regel darin gewinnt gegen die Roles. Siehe Berechtigungen.

curl -X PATCH -b cookies.txt \
  -H "Origin: https://api.example.com" \
  -H "Content-Type: application/json" \
  -d '{"roles":["administrator"]}' \
  https://api.example.com/v1/organization/members/u_456

Rollen-IDs in Pfaden müssen zum Schema passen. Nennt eine Änderung an einem Mitglied eine fehlende Rolle, kommt 404 RoleNotFound.

Ein Member entfernen

DELETE /v1/organization/members/:userId entfernt das Member und widerruft seine Tokens. Es braucht write auf Member. Wenn seine E-Mail-Domain noch bestätigt ist und joinByDomain an ist, oder wenn es sich über eine SSO-Verbindung anmeldet, tritt es bei der nächsten Anmeldung wieder bei. Um es draußen zu halten, sperre es.

Regeln für Super Administrators

Nur ein Super Administrator kann einen Super Administrator ändern oder entfernen oder jemandem diese Role geben.
Nur ein Super Administrator kann einem Member eine Policy mit Allow-Regeln geben oder super_administrator in die Standard-Roles eintragen. Andere Administratoren können nur Policies mit Deny-Regeln geben. So kann niemand mehr vergeben, als er selbst hat.
Die Organisation behält immer mindestens einen aktiven Super Administrator. Eine Änderung, die das verletzt, ergibt 409 mit LastSuperAdministrator.

Einladungen

Ein Administrator lädt eine Person per E-Mail ein. Die Person meldet sich mit dieser E-Mail an und nimmt dann an oder lehnt ab. OpenBot sendet keine E-Mail. Sag es der Person selbst.

POST /v1/organization/invitations erstellt eine Einladung. Es braucht write auf Member.

curl -b cookies.txt \
  -H "Origin: https://api.example.com" \
  -H "Content-Type: application/json" \
  -d '{"email":"grace@example.com","roles":["member"]}' \
  https://api.example.com/v1/organization/invitations

{
  "id": "inv_51c2",
  "organizationId": "org_8f3a",
  "organizationName": "Example",
  "email": "grace@example.com",
  "roles": ["member"],
  "status": "pending",
  "invitedBy": "u_123",
  "createdAt": "2026-10-23T09:00:00.000Z",
  "expiresAt": "2026-10-30T09:00:00.000Z"
}

Ohne roles bekommt die Person die defaultRoles der Organisation. Jede Role muss existieren, sonst gibt OpenBot 404 mit RoleNotFound zurück.
Nur ein Super Administrator kann mit der Role super_administrator einladen.
Eine Einladung gilt 7 Tage. Danach ist ihr status expired.
Eine E-Mail kann in einer Organisation nur eine offene Einladung haben. OpenBot gibt 400 mit InvitationInvalid zurück, wenn es schon eine gibt oder wenn ein Member diese E-Mail schon hat.

Du kannst auch Personen einladen, einen Bot zu nutzen. Siehe Bots teilen.

GET /v1/organization/invitations listet die Einladungen auf, die neuesten zuerst. Es braucht read auf Member. Füge ?status=pending hinzu, um nur die offenen zu sehen. DELETE /v1/organization/invitations/:invitationId nimmt eine offene Einladung zurück. Es braucht write auf Member.

Auf eine Einladung antworten

Diese Routen sind für die eingeladene Person. Sie brauchen keine Mitgliedschaft.

GET /v1/invitations listet die offenen Einladungen für deine geprüfte E-Mail auf. Eine Einladung, einen Bot zu nutzen, hat bot und keine roles. Nimm sie mit POST /v1/bot-invitations/accept an. Siehe Bots teilen.
POST /v1/invitations/:invitationId/accept macht dich zum Member mit den Roles der Einladung. Es gibt die Organisation zurück.
POST /v1/invitations/:invitationId/decline lehnt ab.

Nutze zum Antworten das Session-Cookie, kein User-Token. Deine E-Mail muss geprüft sein und gleich der E-Mail der Einladung sein. Eine Einladung für eine andere E-Mail antwortet mit 404 und InvitationNotFound.

curl -X POST -b cookies.txt \
  -H "Origin: https://api.example.com" \
  https://api.example.com/v1/invitations/inv_51c2/accept

Audit-Log

Das Audit-Log zeichnet wichtige Änderungen auf. Nichts kann einen Eintrag ändern oder entfernen. GET /v1/organization/audit_logs listet Einträge auf, die neuesten zuerst. Es braucht read auf AuditLog.

Query	Was es tut
`limit`	1 bis 100. Der Standard ist 50.
`after`	Der Wert `next` der letzten Seite.
`action`	Nur Einträge mit dieser Aktion.
`actor`	Nur Einträge des Members mit dieser User-ID.

{
  "items": [
    {
      "id": "42",
      "createdAt": "2026-10-21T09:05:00.000Z",
      "action": "member.updated",
      "actor": {
        "kind": "member",
        "userId": "u_123",
        "organizationId": "org_8f3a"
      },
      "resource": "openbot.org.org_8f3a.user.u_456",
      "details": {
        "before": { "status": "active", "roles": ["member"], "policyRules": 0 },
        "after": {
          "status": "active",
          "roles": ["administrator"],
          "policyRules": 0
        }
      }
    }
  ],
  "next": "42"
}

Aktion	Wann
`member.joined`	Ein Konto tritt der Organisation bei.
`member.updated`	Ein Member bekommt einen neuen Status, Roles oder eine Policy.
`member.removed`	Ein Member wird entfernt.
`member.left`	Ein Member verlässt die Organisation.
`invitation.created`	Ein Member lädt eine E-Mail ein.
`invitation.revoked`	Ein Member nimmt eine Einladung zurück.
`invitation.accepted`	Die eingeladene Person nimmt an.
`invitation.declined`	Die eingeladene Person lehnt ab.
`organization.created`	Jemand erstellt eine Organisation.
`organization.updated`	Die Organisation bekommt einen neuen Namen.
`settings.updated`	Die Einstellungen der Organisation ändern sich.
`role.created`	Ein Member erstellt eine eigene Role.
`role.updated`	Ein Member ändert eine eigene Role.
`role.deleted`	Ein Member löscht eine eigene Role.
`model.created`	Ein Member fügt ein Model hinzu.
`model.updated`	Ein Member ändert ein Model.
`model.deleted`	Ein Member entfernt ein Model.
`model_provider.created`	Ein Member fügt einen Model Provider hinzu.
`model_provider.updated`	Ein Member ändert einen Model Provider.
`model_provider.deleted`	Ein Member entfernt einen Model Provider.
`domain.added`	Ein Member fügt eine E-Mail-Domain hinzu.
`domain.verified`	Eine E-Mail-Domain wird bestätigt.
`domain.removed`	Ein Member entfernt eine E-Mail-Domain.
`sso_connection.created`	Ein Member fügt eine SSO-Verbindung hinzu.
`sso_connection.updated`	Ein Member ändert eine SSO-Verbindung.
`sso_connection.deleted`	Ein Member entfernt eine SSO-Verbindung.
`token.created`	Ein Member erstellt ein User-Token.
`token.revoked`	Ein Member widerruft ein User-Token.
`bot.created`	Ein Member erstellt einen Bot.
`bot.updated`	Ein Member ändert einen Bot.
`bot.memory.updated`	Ein Member ändert Bot-Memory.
`bot.memory.purged`	Ein Member entfernt Bot-Memory nach einem Tag.
`bot.memory_bot.updated`	Ein Member ändert den Memory-Bot.
`delegation.started`	Ein Bot gibt Arbeit an einen Bot.
`delegation.completed`	Abgegebene Arbeit endet.
`capability.decided`	Eine Person beantwortet einen Request.
`request.resolved`	Ein Request wird geschlossen. `details.chain` listet die Bots auf.
`grant.created`	Ein Member erstellt einen Grant.
`grant.revoked`	Ein Member widerruft einen Grant.
`rule.created`	Ein Member fügt eine Rule hinzu.
`rule.updated`	Ein Member ändert eine Rule.

Fehler

InvitationNotFound gibt 404 zurück. Wenn die Anfrage eine Einladung nennt, enthält der Fehler invitationId. Passt das Secret eines Bot-Links zu keiner Einladung, fehlt dieses Feld.

Status	Fehler	Wann
`400`	`InvitationInvalid`	Die Einladung kann jetzt nicht erstellt oder beantwortet werden, zum Beispiel weil sie abgelaufen ist.
`404`	`InvitationNotFound`	Es gibt keine Einladung mit dieser ID für dich.
`404`	`RoleNotFound`	Eine Einladung nennt eine Role, die es nicht gibt.
`403`	`Forbidden`	Die Policy des Aufrufers erlaubt es nicht. Siehe Berechtigungen.
`400`	`OrganizationRequired`	Eine Anfrage mit Cookie ohne `OpenBot-Organization`, und du hast mehr als eine Organisation.
`400`	`SettingsInvalid`	Ein Wert in den Einstellungen ist ungültig, zum Beispiel eine Role, die es nicht gibt.
`403`	`MembershipRequired`	Du bist kein aktives Member der Organisation.
`403`	`OrganizationCreationDisabled`	Auf dieser Platform können nur Platform-Admins Organisationen erstellen.
`404`	`MemberNotFound`	Kein Member hat diese User-ID.
`409`	`SettingsConflict`	Jemand hat die Einstellungen geändert, nachdem du sie gelesen hast.
`409`	`LastSuperAdministrator`	Nach der Änderung gäbe es keinen aktiven Super Administrator mehr.
`503`	`OrganizationStorageUnavailable`	OpenBot erreicht seine Datenbank nicht.