Organization

This page shows how many people share OpenBot. An organization is a group of people who share Agents, models and settings. One platform has many organizations. One account can be a member of many of them. One person who uses OpenBot alone has an organization with one member.

The routes of the current organization are under /v1/organization. They accept a user token or the session cookie. With the cookie, send the OpenBot-Organization header when you belong to more than one organization. See Authentication.

Who can join

Each time an account signs in, OpenBot checks where it belongs. It also checks on each request with the session cookie.

Way	Role it gets	Needs
Verified domain	The `defaultRoles` of the organization	The organization verified the domain of the email, `joinByDomain` is `true`, and the provider verified the email.
SSO connection	The `defaultRoles` of the organization	The account signed in through the SSO connection of the organization.
Personal organization	`super_administrator` in a new organization named “Personal”	The account has no organization, and `organizationCreation` in the platform settings is `anyone`.
New organization	`super_administrator`	The account calls `POST /v1/organizations`. See Create an organization.

An account without any organization gets 403 with MembershipRequired from organization routes. See SSO and domains to verify a domain, and Platform for organizationCreation.

Your organizations

GET /v1/organizations lists the organizations where you are a member. A user token sees only its own organization.

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 is active or suspended. A platform admin can suspend an organization. Then nobody can use it, and its tokens stop working. See Platform.

Create an organization

POST /v1/organizations creates an organization. You become its 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

When organizationCreation in the platform settings is platform_admins, only platform admins can do this. Other callers get 403 with OrganizationCreationDisabled.

Read and change the organization

GET /v1/organization reads the current organization. It returns the same object as above. PATCH /v1/organization changes its name. It needs organization.write.

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

Settings

Each organization has its own settings. They live in the database, so every OpenBot instance uses the same values. GET /v1/organization/settings reads them. It needs organization.read.

{
  "version": 2,
  "rulesModel": {
    "_tag": "Config.Selection",
    "provider": "prov_4c1e...",
    "model": "gpt-4.1-mini"
  },
  "agentMemoryModel": null,
  "decisionModel": null,
  "memory": { "use": true, "generate": true },
  "agentMemory": true,
  "requestTimeoutMs": 86400000,
  "planApproval": {
    "approver": "chain",
    "timeoutMs": 86400000,
    "onTimeout": "stay"
  },
  "appReadRules": [],
  "defaultRoles": ["member"],
  "joinByDomain": true,
  "updatedAt": "2026-10-21T09:00:00.000Z"
}

Field	Default	What it does
`rulesModel`	`null`	The model that judges Rules. `null` means that no model judges them. See Models.
`agentMemoryModel`	`null`	The model that learns Agent memory. `null` means that Agents learn nothing.
`decisionModel`	`null`	The decision model, such as Jev. It must be a `decision` model. `null` means none. See Models.
`memory`	both on	The memory switches `use` and `generate` of a new Session. See Memory.
`agentMemory`	`true`	Learn Agent memory after each Turn.
`requestTimeoutMs`	24 hours	How long a request waits for an answer before OpenBot denies it. From 1 second to 7 days.
`planApproval`	ask the decider above, stay a plan after 24 hours	How a plan is approved when no member, Agent or Session sets it. See Plan mode.
`appReadRules`	`[]`	App tools that only read: `{ cardUrl, tool }`. See Requests.
`defaultRoles`	`["member"]`	The roles of a new member.
`joinByDomain`	`true`	People with a verified email in a verified domain of the organization join when they sign in.

PATCH /v1/organization/settings changes them. It needs organization.write. The body needs expectedVersion, the version that you read. Add only the fields that you want to change.

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

If someone changed the settings after you read them, OpenBot returns 409 with SettingsConflict and the current version. Read them again, then try again.
A role that does not exist returns 400 with SettingsInvalid.
Only a Super Administrator can put super_administrator in defaultRoles.

Every instance uses a change at once. See Configuration.

Members

GET /v1/organization/members lists members in pages. It needs members.read. Use limit (1 to 100, default 50) and after with the next value of the last page.

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

GET /v1/organization/members/:userId reads one member.

Change a member

PATCH /v1/organization/members/:userId changes status, roles or policies. It needs members.write.

status is active or suspended. A suspended member cannot use this organization, and their tokens for it stop working at once.
roles is a list of role IDs: built-in roles and custom roles. See Permissions.
policies are extra policies for the member, on top of their roles.

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

Remove a member

DELETE /v1/organization/members/:userId removes the member and revokes their tokens. It needs members.write. If their email domain is still verified and joinByDomain is on, or they sign in through an SSO connection, they join again the next time they sign in. To keep them out, suspend them.

Rules for Super Administrators

Only a Super Administrator can change or remove a Super Administrator, or give someone the role.
Only a Super Administrator can give a member extra allow policies, or put super_administrator in the default roles. Other administrators can only add deny policies. So nobody can give more than they have.
The organization keeps at least one active Super Administrator. A change that breaks this returns 409 with LastSuperAdministrator.

Audit log

The audit log records important changes. Nothing can change or remove an entry. GET /v1/organization/audit_logs lists entries, newest first. It needs audit_logs.read.

Query	What it does
`limit`	1 to 100. The default is 50.
`after`	The `next` value of the last page.
`action`	Only entries with this action.
`actor`	Only entries by the member with this 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"], "policies": 0 },
        "after": {
          "status": "active",
          "roles": ["administrator"],
          "policies": 0
        }
      }
    }
  ],
  "next": "42"
}

Action	When
`member.joined`	An account joins the organization.
`member.updated`	A member gets a new status, roles or policies.
`member.removed`	A member is removed.
`organization.created`	Someone creates an organization.
`organization.updated`	The organization gets a new name.
`settings.updated`	The organization settings change.
`role.created`	A member makes a custom role.
`role.updated`	A member changes a custom role.
`role.deleted`	A member deletes a custom role.
`model.created`	A member adds a model.
`model.updated`	A member changes a model.
`model.deleted`	A member removes a model.
`model_provider.created`	A member adds a model provider.
`model_provider.updated`	A member changes a model provider.
`model_provider.deleted`	A member removes a model provider.
`domain.added`	A member adds an email domain.
`domain.verified`	An email domain becomes verified.
`domain.removed`	A member removes an email domain.
`sso_connection.created`	A member adds an SSO connection.
`sso_connection.updated`	A member changes an SSO connection.
`sso_connection.deleted`	A member removes an SSO connection.
`token.created`	A member creates a user token.
`token.revoked`	A member revokes a user token.
`agent.created`	A member makes an Agent.
`agent.updated`	A member changes an Agent.
`agent.promoted`	A member promotes a Session Agent.
`agent.memory.updated`	A member changes Agent memory.
`delegation.started`	An Agent gives work to another Agent.
`delegation.completed`	Delegated work ends.
`capability.decided`	A person answers a request.
`request.resolved`	A request closes. `details.chain` lists the Agents.
`grant.created`	A member makes a Grant.
`grant.revoked`	A member revokes a Grant.
`rule.created`	A member adds a Rule.
`rule.updated`	A member changes a Rule.

Errors

Status	Error	When
`400`	`PolicyInvalid`	A policy names a resource outside the organization.
`403`	`PermissionDenied`	The caller does not have the permission. See Permissions.
`400`	`OrganizationRequired`	A cookie request without `OpenBot-Organization`, and you have more than one organization.
`400`	`SettingsInvalid`	A value in the settings is not valid, such as a role that does not exist.
`403`	`MembershipRequired`	You are not an active member of the organization.
`403`	`OrganizationCreationDisabled`	Only platform admins can create organizations on this platform.
`404`	`MemberNotFound`	No member has this user ID.
`409`	`SettingsConflict`	Someone changed the settings after you read them.
`409`	`LastSuperAdministrator`	The change would leave no active Super Administrator.
`503`	`OrganizationStorageUnavailable`	OpenBot cannot reach its database.