diff --git a/.claude/skills/openbot-copy/SKILL.md b/.claude/skills/openbot-copy/SKILL.md
index c3a0abee95..231b0263f2 100644
--- a/.claude/skills/openbot-copy/SKILL.md
+++ b/.claude/skills/openbot-copy/SKILL.md
@@ -28,6 +28,9 @@ One word for one thing, everywhere a person can see it.
| **connect / disconnect / reconnect** | What a person does to their own account. | link (except GitHub and Slack identity, where "link" is the vendor's own word) |
| **skill** | A named instruction invoked with `/`. | command, prompt |
| **admin** | The person who runs OpenBot for everybody. | administrator, owner, operator |
+| **organization**, **everyone in the organization** | Everybody who uses OpenBot together, and what is theirs as a whole: "everyone in the organization", "organization rules", "your organization's shared account". | team, the whole team, teammates, organisation |
+| **team**, **Teams** | A named group of people inside one organization, made in Admin under Teams or kept in step with the company's directory. Whatever can be given to everyone can be given to a team. | group (for a team), and never the whole organization |
+| **shared account** | An app account the organization connects once, which Bots act as. | team account |
| **OpenBot** | The product the person is using, and their account with it: "Sign in to OpenBot", "your OpenBot account". | this deployment, the server, the instance, CopilotKit |
| **OpenBot by CopilotKit** | The company, only where it has to be named: the license agreement's name, a legal or privacy line, the one place setup says who makes OpenBot. | CopilotKit alone |
| **turn on / turn off** | An admin switching an app or a feature. | enable / disable (in sentences; a switch may still read "Enabled") |
@@ -101,7 +104,11 @@ because the admin is the one who sets them. A page anybody can open may not.
8. **Buttons are verbs**: Connect, Request access, Create, Save. A button never says "Click here" or
"OK" when it does something specific.
9. **Errors**: what failed, in the person's terms, and one next step. "Couldn't load your
- connections. Reload the page." No stack of reasons, no blame.
+ connections. Try again in a moment." No stack of reasons, no blame. Never "Reload the page": the
+ same screens show in the OpenBot Desktop window, which has no reload button. While OpenBot
+ Desktop can't reach the OpenBot it is connected to, one line says so and the screens wait
+ (`lib/desktop/connection-lost.ts`), so a section's error is never the place to name that cause.
+ `tests/no-reload-the-page-in-user-copy.test.ts` reads every shown string.
10. **Empty states** say what will appear and how: "No skills yet. Write one with New skill."
## Before And After
@@ -109,7 +116,7 @@ because the admin is the one who sets them. A page anybody can open may not.
| Before | After |
|---|---|
| The apps and accounts your Bots use as you. Open one to connect it or change it. | Connect your accounts so Bots can use apps on your behalf. |
-| Your connected accounts could not be loaded, so nothing is listed here rather than a list that may be wrong. Reload the page, and tell an administrator if it persists. | Couldn't load your connections. Reload the page, or ask an admin if it keeps happening. |
+| Your connected accounts could not be loaded, so nothing is listed here rather than a list that may be wrong. Reload the page, and tell an administrator if it persists. | Couldn't load your connections. Try again in a moment, or ask an admin if it keeps happening. |
| Sent to the coworker it is for. Type @ to choose one yourself. | OpenBot picks the right Bot. Type @ to choose one. |
| Gmail is a Composio app, and this deployment has no Composio key. (to a non-admin) | Gmail isn't set up yet. An admin has to turn it on. |
| The agent is still working on another request. Please wait or stop that task first. | This Bot is still working on something. Wait for it, or stop it first. |
@@ -120,6 +127,7 @@ because the admin is the one who sets them. A page anybody can open may not.
|---|---|
| "agent" or "coworker" for a Bot | Bot |
| "administrator" | admin |
+| "team", "the whole team" or "teammates" for everybody | "everyone in the organization", or "organization"; a team is one named group inside it |
| "this deployment" on a page anybody can open | OpenBot, or say what is missing |
| "CopilotKit" alone: "Sign in to CopilotKit", "your CopilotKit account" | OpenBot, or "OpenBot by CopilotKit" where the company must be named |
| A sentence over ~25 words | Split it, or cut the clause that justifies the screen |
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9b72b7ab19..d36f230750 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -190,9 +190,13 @@ jobs:
# holding still as an update gets ready, Home's message box holding still while the
# microphone's notice shows, a reply staying where it was written once its turn is over,
# every skin's top-left corner clear of the Mac window's buttons, OpenDots' Bots badge on its
- # icon's corner inside the rail, the version in the account row read whole, a Bot's orb
- # one color in the sidebar, on its page and at the top of its conversation, and Record on
- # screen with a Bot's page in a window of any width, which only a browser's layout, cascade
+ # icon's corner inside the rail, the version in the account row read whole, an organization's
+ # name in the account menu read whole or in a tooltip, a Bot's orb
+ # one color in the sidebar, on its page and at the top of its conversation, Record on
+ # screen with a Bot's page in a window of any width, the team screens and a Bot's
+ # Publish dialog holding their layout wide, narrow and on a phone, and the Admin screens
+ # where a rule or a grant names a team holding theirs wide and on a phone, which only a
+ # browser's layout, cascade
# and paint resolve, and the app following the system's light or dark, which only a
# browser's `prefers-color-scheme` reports, with what OpenBot Desktop's window is told of
# it. The
@@ -200,7 +204,7 @@ jobs:
# test script's pretest does).
- run: |
bun run generate:app-config
- bun test app/tests/tool-line-reduced-motion.test.tsx app/tests/onboarding-window-buttons.test.tsx app/tests/onboarding-orb-room.test.tsx app/tests/transcript-rail-clearance.test.tsx app/tests/a2ui-frame.test.tsx app/tests/update-banner-layout.test.tsx app/tests/composer-dictation-notice-layout.test.tsx app/tests/conversation-intro-halo.test.tsx app/tests/transcript-room.test.tsx app/tests/skins-window-buttons.test.tsx app/tests/opendots-rail-badge.test.tsx app/tests/account-version-layout.test.tsx app/tests/bot-orb-one-color.test.tsx app/tests/theme-follows-system.test.tsx app/tests/desktop-window-theme.test.tsx app/tests/bot-screen-record-layout.test.tsx
+ bun test app/tests/tool-line-reduced-motion.test.tsx app/tests/onboarding-window-buttons.test.tsx app/tests/onboarding-orb-room.test.tsx app/tests/transcript-rail-clearance.test.tsx app/tests/a2ui-frame.test.tsx app/tests/update-banner-layout.test.tsx app/tests/composer-dictation-notice-layout.test.tsx app/tests/conversation-intro-halo.test.tsx app/tests/transcript-room.test.tsx app/tests/skins-window-buttons.test.tsx app/tests/opendots-rail-badge.test.tsx app/tests/account-version-layout.test.tsx app/tests/organization-menu-names.test.tsx app/tests/bot-orb-one-color.test.tsx app/tests/theme-follows-system.test.tsx app/tests/desktop-window-theme.test.tsx app/tests/bot-screen-record-layout.test.tsx app/tests/teams-screens-layout.test.tsx app/tests/team-grants-screens-layout.test.tsx
env:
OPENBOT_APP_BROWSER: '1'
# The desktop setup window's, for the same reason: the AI step's form holding still while the
diff --git a/.github/workflows/desktop-build.yml b/.github/workflows/desktop-build.yml
index 7de63f4918..a29f8ac9a8 100644
--- a/.github/workflows/desktop-build.yml
+++ b/.github/workflows/desktop-build.yml
@@ -85,7 +85,7 @@ jobs:
with:
bun-version: 1.4.3
no-cache: ${{ inputs.channel == 'release' || runner.os == 'Windows' }}
- - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
+ - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1
with:
toolchain: stable
- if: inputs.channel != 'release'
diff --git a/.github/workflows/desktop-macos-signing.yml b/.github/workflows/desktop-macos-signing.yml
index b4d1c5a7fb..a867058cfe 100644
--- a/.github/workflows/desktop-macos-signing.yml
+++ b/.github/workflows/desktop-macos-signing.yml
@@ -301,7 +301,7 @@ jobs:
# must come from the tree and the lockfiles, not from anything an earlier run left behind.
# The standard library for the architecture this job builds, which on the Apple silicon
# runner is a second target for the Intel build.
- - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
+ - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1
with:
toolchain: stable
targets: ${{ matrix.platform.rust-target }}
diff --git a/.github/workflows/desktop-shell-updates.yml b/.github/workflows/desktop-shell-updates.yml
index 39087a9594..121a15ff1d 100644
--- a/.github/workflows/desktop-shell-updates.yml
+++ b/.github/workflows/desktop-shell-updates.yml
@@ -69,7 +69,7 @@ jobs:
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
bun-version: 1.4.3
- - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
+ - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1
with:
toolchain: stable
- name: Linux packaging dependencies
diff --git a/.github/workflows/desktop-signing.yml b/.github/workflows/desktop-signing.yml
index d47e0d4962..eed32a6195 100644
--- a/.github/workflows/desktop-signing.yml
+++ b/.github/workflows/desktop-signing.yml
@@ -134,7 +134,7 @@ jobs:
with:
bun-version: 1.4.3
no-cache: true
- - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
+ - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1
with:
toolchain: stable
- name: Install pinned AzureSignTool
diff --git a/.github/workflows/desktop.yml b/.github/workflows/desktop.yml
index 9eb018f3f9..b492ff884b 100644
--- a/.github/workflows/desktop.yml
+++ b/.github/workflows/desktop.yml
@@ -41,7 +41,7 @@ jobs:
with:
ref: ${{ github.event.pull_request.head.sha || github.sha }}
persist-credentials: false
- - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
+ - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1
with:
toolchain: stable
components: rustfmt, clippy
diff --git a/.github/workflows/publish-release.yml b/.github/workflows/publish-release.yml
index 99b02c8145..7870df3c61 100644
--- a/.github/workflows/publish-release.yml
+++ b/.github/workflows/publish-release.yml
@@ -610,7 +610,7 @@ jobs:
with:
bun-version: 1.4.3
no-cache: true
- - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
+ - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1
with:
toolchain: stable
- run: |
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 56df252441..4257402222 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -34,6 +34,16 @@ every deployment:
### OpenBot Desktop
+- **OpenBot Desktop can connect to an OpenBot that runs somewhere else.** At set-up, and later in
+ Settings, Computer, choose between OpenBot on this computer, as before, and an OpenBot at an
+ address you type, such as your company's. Connected, nothing is installed or started on this
+ computer and no CopilotKit account is asked for: you sign in to that OpenBot in your browser, and
+ the app keeps the sign-in in Keychain or Windows Credential Manager, never in a file. Settings
+ shows where the app is connected, with Sign out and a way back to OpenBot on this computer,
+ which loses nothing. Starting, stopping and updating OpenBot's services, model keys and local
+ folders for Bots belong to OpenBot on this computer and are not shown while connected. It needs
+ an OpenBot whose server honours an app's sign-in for its screens; an earlier one is refused with
+ a sentence saying so.
- **OpenBot Desktop is one address.** With CopilotKit Intelligence on the same machine, the app
used to open a second connection, straight to Intelligence's gateway on a port of its own. It now
opens everything on OpenBot's own address: the server carries that socket
@@ -350,6 +360,11 @@ earlier release's is one top-level line in it, `x-openbot-scheduled-work: server
person, is sent as `Authorization: Bearer` or `x-api-key`, and works on `/api/v2` only. The
server also issues access tokens through OAuth 2.1 with PKCE, which work on `/api/v2` only too.
Both end when the person is removed.
+- **Settings has an API keys page.** Under You, a signed-in person lists their keys, creates one
+ by name and revokes one. A new key is shown once, with Copy. OpenBot on one computer for one
+ person has no sign-in and says it has no keys, and OpenBot Desktop connected to an OpenBot
+ elsewhere opens the page in your browser. The spec now lists what an app needs for OAuth: the
+ client ids, redirect addresses, endpoints and how long tokens last.
- **The web app calls the new addresses**, through a client generated from the spec, for Bots,
the audit trail, accounts, admin settings, model connections, notifications, routines,
conversations and approvals, and opens its sockets there. Apps, connections, a Bot's grants,
diff --git a/api/accepted-breaking-changes.md b/api/accepted-breaking-changes.md
index 2b2f036998..e03406dba2 100644
--- a/api/accepted-breaking-changes.md
+++ b/api/accepted-breaking-changes.md
@@ -34,3 +34,14 @@ Once the change is on the base branch, oasdiff no longer reports it and its line
- 2026-11-14 POST /api/v2/organizations/{organizationId}/people/{personId}/revoke-access added the new `member` enum value to the `person/role` response property for the response status `200`. Renamed before any release to the organisation-member roles: owner, admin and member, where a person was admin or user.
- 2026-11-14 POST /api/v2/organizations/{organizationId}/people/{personId}/revoke-access added the new `owner` enum value to the `person/role` response property for the response status `200`. Renamed before any release to the organisation-member roles: owner, admin and member, where a person was admin or user.
- 2026-11-14 PATCH /api/v2/organizations/{organizationId}/capabilities/{capabilityId} removed the request property `roles/user`. Renamed before any release to the organisation-member roles: owner, admin and member, where a person was admin or user.
+- 2026-11-15 POST /api/v2/organizations/{organizationId}/members api removed without deprecation. Adding somebody who already had an account, by email, was described before any release and no release serves it. People join an organization by invitation: POST /api/v2/organizations/{organizationId}/invitations, which the person accepts.
+- 2026-11-15 PUT /api/v2/organizations/{organizationId}/apps/{appId}/account-mode added the new `team` enum value to the `bots/items/approval/members/items/kind` response property for the response status `200`. A shared account's audience can now name a team by id beside a person and a directory group; nothing is taken from a client, and one written before teams never sent or approved a team.
+- 2026-11-15 GET /api/v2/organizations/{organizationId}/bots/{botId}/shared-use added the new `team` enum value to the `apps/items/approval/oneOf[#/components/schemas/SharedUseApproval]/members/items/kind` response property for the response status `200` (shared schema: `SharedUseApproval`, also at `apps/items/needed/members/items/kind`, `pending/items/current/oneOf[#/components/schemas/SharedUseApproval]/members/items/kind` and 1 more). A shared account's audience can now name a team by id beside a person and a directory group; nothing is taken from a client, and one written before teams never sent or approved a team.
+- 2026-11-15 POST /api/v2/organizations/{organizationId}/capabilities/batch-update added the new `team` enum value to the `saved/items/scopeKind` response property for the response status `200`. A permission switch can now be set for a team by id, beside the organization, a role and a directory group; a client that never set one never reads one.
+- 2026-11-15 POST /api/v2/organizations/{organizationId}/capabilities/preview added the new `team` enum value to the `people/items/capabilities/items/after/decidedBy` response property for the response status `200` (shared schema: `CapabilityAnswer`, also at `people/items/capabilities/items/before/decidedBy`). A team's switch can now be the one that decides a person's permission, as a directory group's can.
+- 2026-11-15 POST /api/v2/organizations/{organizationId}/capabilities/translate added the new `team` enum value to the `changes/items/scopeKind` response property for the response status `200`. A permission switch can now be set for a team by id, beside the organization, a role and a directory group; a client that never set one never reads one.
+- 2026-11-15 GET /api/v2/organizations/{organizationId}/network-policies added the new `team` enum value to the `networkPolicies/items/scopeKind` response property for the response status `200`. A network policy can now be set for a team by id, beside the organization and a directory group; a client that never set one never reads one.
+- 2026-11-15 PUT /api/v2/organizations/{organizationId}/network-policies/{networkPolicyId} added the new `team` enum value to the `scopeKind` response property for the response status `200`. A network policy can now be set for a team by id, beside the organization and a directory group; a client that never set one never reads one.
+- 2026-11-15 GET /api/v2/organizations/{organizationId}/shared-use-requests added the new `team` enum value to the `sharedUseRequests/items/current/oneOf[#/components/schemas/SharedUseApproval]/members/items/kind` response property for the response status `200` (shared schema: `SharedUseApproval`, also at `sharedUseRequests/items/proposed/members/items/kind`). A shared account's audience can now name a team by id beside a person and a directory group; nothing is taken from a client, and one written before teams never sent or approved a team.
+- 2026-11-15 POST /api/v2/organizations/{organizationId}/shared-use-requests/{sharedUseRequestId}/approve added the new `team` enum value to the `current/oneOf[#/components/schemas/SharedUseApproval]/members/items/kind` response property for the response status `200` (shared schema: `SharedUseApproval`, also at `proposed/members/items/kind`). A shared account's audience can now name a team by id beside a person and a directory group; nothing is taken from a client, and one written before teams never sent or approved a team.
+- 2026-11-15 POST /api/v2/organizations/{organizationId}/shared-use-requests/{sharedUseRequestId}/decline added the new `team` enum value to the `current/oneOf[#/components/schemas/SharedUseApproval]/members/items/kind` response property for the response status `200` (shared schema: `SharedUseApproval`, also at `proposed/members/items/kind`). A shared account's audience can now name a team by id beside a person and a directory group; nothing is taken from a client, and one written before teams never sent or approved a team.
\ No newline at end of file
diff --git a/api/asyncapi.yaml b/api/asyncapi.yaml
index e4461570dc..d3b64aff46 100644
--- a/api/asyncapi.yaml
+++ b/api/asyncapi.yaml
@@ -61,8 +61,18 @@ servers:
join token carries the address to dial with it (realtime.clientUrl).
Where Intelligence runs beside an OpenBot, that address is OpenBot's
own, so a client dials one host: either /api/intelligence/client, which
- OpenBot relays and which also asks for the person's session, or
- /client, which the deployment's edge sends straight to the gateway.
+ OpenBot relays, or /client, which the deployment's edge sends straight
+ to the gateway. The relayed address also asks who is connecting, with
+ the same credential that made the join token: the web app's session, an
+ app's access token (conversations:read) or an API key, the last two as
+ Authorization: Bearer on the request that opens the socket, or a key in
+ an x-api-key header. So a script that holds only an API key mints a
+ join token with it and opens the socket with it. A credential that is
+ not valid is answered 401 before the socket opens. A join token the
+ gateway refuses, because it was used already or has expired, closes the
+ relayed socket with code 1008 and the reason "This join token has been
+ used or has expired. Ask for a new one."; 1011 means the gateway could
+ not be reached at all.
security:
- $ref: "#/components/securitySchemes/joinToken"
voiceService:
@@ -187,8 +197,11 @@ channels:
A Bot's runs in one conversation thread, as AG-UI events, on the
gateway's socket for clients. The socket speaks the Phoenix Channels
protocol, version 2: every frame is a JSON array of five items, [join
- reference, reference, topic, event, payload]. The topic is
- thread:{threadId}, and a join token opens exactly one thread.
+ reference, reference, topic, event, payload]. The topic is the one the
+ REST answer gave as realtime.topic, and a join token opens exactly one
+ thread. The topic names the thread as the gateway knows it, which in an
+ organization other than default is not the threadId a client has, so a
+ client uses the topic as given and never makes one from threadId.
A client joins the topic, and the gateway answers with connected, then
@@ -540,7 +553,8 @@ components:
organizationId:
description: >-
The organization, by its id or its slug, which the caller must be a
- member of. Every install has one addressed as default.
+ member of. One the caller is not in answers as one that does not
+ exist, default included.
botId:
description: The Bot whose computer it is.
messages:
@@ -1142,7 +1156,9 @@ components:
ThreadTopic:
type: string
pattern: ^thread:.+$
- description: The thread, as thread:{threadId}.
+ description: >-
+ The thread, as thread: and the gateway's name for it: the topic the
+ REST answer gave (realtime.topic), used as given.
ThreadJoinFrame:
type: array
description: "[join reference, reference, topic, \"phx_join\", payload]"
diff --git a/api/client-boundary.allow.ts b/api/client-boundary.allow.ts
index 1418acd262..8caca0162f 100644
--- a/api/client-boundary.allow.ts
+++ b/api/client-boundary.allow.ts
@@ -304,6 +304,31 @@ export const ALLOWED: Allowed[] = [
rule: "hand-built-v2",
why: "the Recorder host's handoff, from Rust, which has no generated client",
},
+ // Desktop connecting to an OpenBot that runs somewhere else.
+ {
+ file: "desktop/src-tauri/src/connected/address.rs",
+ what: "/api/v2/organizations/default/deployment",
+ rule: "hand-built-v2",
+ why: "whether the address a person typed is an OpenBot, asked from Rust before anybody signs in",
+ },
+ {
+ file: "desktop/src-tauri/src/connected/address.rs",
+ what: "/.well-known/oauth-authorization-server/api/auth",
+ rule: "before-sign-in",
+ why: "OAuth's discovery document, which names the sign-in's addresses",
+ },
+ {
+ file: "desktop/src-tauri/src/connected/sign_in.rs",
+ what: "/api/copilotkit/info",
+ rule: "runtime",
+ why: "whether the OpenBot serves its runtime to an app's sign-in, asked once after signing in",
+ },
+ {
+ file: "desktop/src-tauri/src/connected/relay.rs",
+ what: /^\/(api\/?|\.well-known\/)$/,
+ rule: "transport",
+ why: "the relay that carries the window's requests to the OpenBot it is connected to: the starts of the paths it signs in, naming no address of its own",
+ },
// Path tables the server registers today's routes from.
...["shared/bot-browser.ts", "shared/openbot-browser.ts"].map(
(file): Allowed => ({
diff --git a/api/openapi-bot-grants.test.ts b/api/openapi-bot-grants.test.ts
index b08ef1db4f..cb4f92aa50 100644
--- a/api/openapi-bot-grants.test.ts
+++ b/api/openapi-bot-grants.test.ts
@@ -82,12 +82,14 @@ test("each operation asks for its area's permission, read to look and write to c
"deleteAppAccessRequest",
"deleteBotGrant",
"dismissAppAccessRequest",
+ "getAppTeamGrants",
"getBotApp",
"giveBotApp",
"listAppAccessRequests",
"listBotApps",
"listBotGrants",
"listGiveableApps",
+ "replaceAppTeamGrants",
"replaceBotGrant",
"replayBotGrants",
"takeBackBotApp",
diff --git a/api/openapi-components.test.ts b/api/openapi-components.test.ts
index 5c0b446f9c..472054758c 100644
--- a/api/openapi-components.test.ts
+++ b/api/openapi-components.test.ts
@@ -86,7 +86,7 @@ test("a skill's slug is the one the skill form lets a person type", () => {
test("each operation asks for its own area's scope: reading to read, writing to change", () => {
const found = operations();
- expect(found).toHaveLength(19);
+ expect(found).toHaveLength(21);
for (const { path, method, tag, scopes } of found) {
const area = tag === "Skills" ? "skills" : "components";
// Checking whether a Bot may draw a component, and reading its data, change nothing a person set.
diff --git a/api/openapi-organizations.test.ts b/api/openapi-organizations.test.ts
new file mode 100644
index 0000000000..05da36cd6a
--- /dev/null
+++ b/api/openapi-organizations.test.ts
@@ -0,0 +1,52 @@
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+
+/**
+ * The list of a person's own organizations, as an app's token reads it. A token carries no session,
+ * so the OpenBot-Organization header says which organization it works in, and the list marks that
+ * one active. The header is checked against the person's membership as on every address that names
+ * no organization, so one they are not in answers not found. The spec declares both, so a client
+ * generated from it knows the header and the answer.
+ */
+
+type Parameter = {
+ name?: string;
+ in?: string;
+ required?: boolean;
+ $ref?: string;
+};
+type Operation = {
+ parameters?: Parameter[];
+ responses?: Record;
+};
+
+const spec = parse(
+ readFileSync(join(import.meta.dir, "openapi.yaml"), "utf8"),
+) as {
+ paths: Record>;
+ components: { parameters: Record };
+};
+
+const listOrganizations = spec.paths["/api/v2/people/me/organizations"]?.get;
+
+const parameters = (listOrganizations?.parameters ?? []).map((parameter) =>
+ parameter.$ref
+ ? spec.components.parameters[
+ parameter.$ref.replace("#/components/parameters/", "")
+ ]
+ : parameter,
+);
+
+test("listOrganizations declares the header an app's token names its organization with", () => {
+ expect(
+ parameters.find((parameter) => parameter?.name === "OpenBot-Organization"),
+ ).toMatchObject({ in: "header", required: false });
+});
+
+test("listOrganizations declares the not found a header naming an organization the caller isn't in answers", () => {
+ expect(listOrganizations?.responses?.["404"]?.$ref).toBe(
+ "#/components/responses/OrganizationNotFound",
+ );
+});
diff --git a/api/openapi.yaml b/api/openapi.yaml
index 4c4461c240..e7279feb85 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -8,7 +8,11 @@ info:
description: |-
The one API every OpenBot client uses: the web app, Desktop, mobile and the Recorder. It follows the conventions of CopilotKit Intelligence's v2 API so both read as one API, and OpenBot's resources sit beside Intelligence's under the same organization address (/api/v2/organizations/{organizationId}/...). Errors are RFC 9457 problem details (application/problem+json), lists page with an opaque cursor and a limit, and every write takes an Idempotency-Key.
- An OpenBot install holds one or more organizations, and a person may be a member of several. Every install has the organization `default`, which is where everybody starts. organizationId is an organization's id or its slug, and the caller must be a member of it: an organization the caller is not in answers exactly as one that does not exist.
+ An OpenBot install holds one or more organizations, and a person may be a member of several. Where an install allows more than one, everybody has an organization of their own, made for them when they first sign in, and joins others by invitation. Otherwise, and on an install for one person with no sign-in, everybody works in the organization `default`. organizationId is an organization's id or its slug, and the caller must be a member of it: an organization the caller is not in answers exactly as one that does not exist, `default` included.
+
+ A program of your own signs its requests in one of two ways. An API key acts as the person who made it, in every organization they are a member of, like a personal access token: the address names the organization each request is for. Keys start `obk_` and are sent as `Authorization: Bearer ` or in an `x-api-key` header, on /api/v2 and on the socket a join token is spent on (createConversationJoinToken). To get a first key, sign in to OpenBot's web app, open Settings, then API keys, and create one. The key is shown once. Only a person signed in to the web app can make or delete keys: a key or an app's sign-in cannot. An app that signs people in uses OAuth 2.1 instead, described under the appOAuth security scheme: its client ids, redirect addresses, endpoints, how long tokens last and the four addresses outside /api/v2 a token also works at.
+
+ An install for one person on one computer has no sign-in. It signs nobody in, so it has neither OAuth nor API keys, and the operations that manage keys and sessions answer 503 with the code SIGN_IN_UNAVAILABLE.
This file is the single source of truth: the clients, the server's types, the docs and the contract tests are all generated from it or checked against it. A change that breaks an existing client fails the pull request.
servers:
@@ -30,7 +34,7 @@ tags:
- name: Identity providers
description: The companies' own identity providers registered for single sign-on, by email domain. Only an administrator manages them.
- name: API keys
- description: The keys a person makes for automation. A key acts as them, inside the organization, on the API only, and only a person signed in to OpenBot can make or manage one.
+ description: The keys a person makes for automation. A key acts as them, in every organization they are a member of, on the API, and only a person signed in to OpenBot can make or manage one.
- name: Sessions
description: Where a person is signed in to OpenBot, so they can see each browser and device and sign one out.
- name: Organization settings
@@ -46,11 +50,11 @@ tags:
- name: Voice
description: 'Voice calls with a conversation''s Bot: how a call connects, and the calls a person saved in a conversation with their transcripts.'
- name: Credentials
- description: 'The vault: the model keys, app keys and app tokens OpenBot keeps encrypted for its Bots. A secret goes in and is never read back out. Only an administrator manages them.'
+ description: 'The organization''s vault: the model keys, app keys and app tokens OpenBot keeps encrypted for its Bots. A secret goes in and is never read back out. Only an administrator manages them.'
- name: Models
description: The models Bots can run on, and the one a person chose for each of their conversations.
- name: Apps
- description: The apps this OpenBot has added for its Bots to use, from the directory of apps it can add or by a server's address, and how apps are set up here.
+ description: The apps the organization has added for its Bots to use, from the directory of apps it can add or by a server's address, and how apps are set up here.
- name: Connections
description: 'A person''s connections to apps: the accounts they signed in with so their Bots can act there for them, and an app''s one shared account when an administrator connects it for everybody.'
- name: Bot grants
@@ -79,6 +83,8 @@ tags:
description: Work a Bot scheduled for itself to come back to later in a conversation.
- name: Organizations
description: The organizations the caller is a member of, and each one's members. An organization keeps its own Bots and conversations, apart from every other's.
+ - name: Teams
+ description: 'An organization''s teams: named groups of its members, and each team''s people. What is granted to a team is its people''s to use, and nobody else''s in the organization. A team is made here or kept in step with a group of the company''s directory.'
- name: Approvals
description: 'What a person''s Bots are waiting on them for: the actions that ask before they run, the questions a Bot asked, and what the person set for themselves about asking (their preferences, their own rules, and what they allowed for one conversation). Each person''s are theirs alone.'
- name: Approval rules
@@ -168,7 +174,7 @@ paths:
- Bots
operationId: listBots
summary: List Bots
- description: 'Return one page of the Bots the caller can see: theirs, the ones shared with them, the ones assigned to them and the ones that come with OpenBot, oldest first, and by id among Bots made at the same moment. hidden=true lists only the Bots the caller hid from their own list instead. A missing cursor starts at the first page and nextCursor null ends the list.'
+ description: 'Return one page of the Bots the caller can see: theirs, the ones shared with them, the ones assigned to them and the ones that come with OpenBot, oldest first, and by id among Bots made at the same moment. Somebody else''s private Bot is never among them, an admin''s list included. hidden=true lists only the Bots the caller hid from their own list instead. scope=organization lists every Bot in the organization, people''s private Bots included, for an admin''s screens that decide what Bots may hold; it is refused to anybody who is not an admin of the organization. Somebody else''s private Bot comes withheld there: its name and avatar, and nothing from inside it (see the Bot''s withheld). A missing cursor starts at the first page and nextCursor null ends the list.'
security:
- webSession: []
- appOAuth:
@@ -181,6 +187,15 @@ paths:
schema:
type: boolean
default: false
+ - name: scope
+ in: query
+ description: 'Whose Bots: caller, the Bots the caller can see; organization, every Bot in the organization, for an admin of it only.'
+ schema:
+ type: string
+ enum:
+ - caller
+ - organization
+ default: caller
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Cursor'
responses:
@@ -412,7 +427,7 @@ paths:
- Audit events
operationId: listAuditEvents
summary: List audit events
- description: Return one page of the audit trail, newest first, narrowed by the filters given. Each filter narrows the events, and a filter that takes several values separated by commas matches any of them. A value that names nothing in the trail matches no event rather than being refused. A missing cursor starts at the newest event and nextCursor null ends the list. A cursor belongs to the filters that made it, so changing a filter starts again without one; limit may change from page to page. Only an administrator may read the trail.
+ description: 'Return one page of the organization''s audit trail, newest first, narrowed by the filters given. Each organization has its own trail, and an event is on the trail of the organization it happened in. What happens to the organization itself is on its trail too: organization.created, organization.renamed, organization.member_invited, organization.invitation_canceled, organization.member_joined, organization.member_removed and organization.member_role_changed. Each filter narrows the events, and a filter that takes several values separated by commas matches any of them. A value that names nothing in the trail matches no event rather than being refused. A missing cursor starts at the newest event and nextCursor null ends the list. A cursor belongs to the filters that made it, so changing a filter starts again without one; limit may change from page to page. Only an administrator of the organization may read its trail.'
security:
- webSession: []
- appOAuth:
@@ -469,7 +484,7 @@ paths:
- Audit events
operationId: exportAuditEvents
summary: Export audit events as CSV
- description: 'Return every event the filters match, newest first, as one CSV file (RFC 4180): the same filters as listing audit events, without its paging, so the file and the list agree. The file holds at most 5,000 events; when more match, OpenBot-Export-Truncated says how many it holds, and narrowing the dates exports the rest. A cell a spreadsheet would run as a formula starts with an apostrophe. Each export is recorded on the trail. Only an administrator may export the trail.'
+ description: 'Return every event the filters match, newest first, as one CSV file (RFC 4180): the same filters as listing audit events, without its paging, so the file and the list agree. The file holds at most 5,000 events; when more match, OpenBot-Export-Truncated says how many it holds, and narrowing the dates exports the rest. A cell a spreadsheet would run as a formula starts with an apostrophe. Each export is recorded on the trail. Only an administrator of the organization may export its trail.'
x-openbot-singleton: true
security:
- webSession: []
@@ -777,7 +792,7 @@ paths:
- People
operationId: revokePersonAccess
summary: Remove a person's access
- description: 'Stop a person from using OpenBot: their address can''t sign in again, and the sessions, API keys and app sign-ins they hold end at once. They keep their record and their history, and restoring their access lets them sign in again. Their connected credentials are retired too. Only an administrator may do this, never to themselves, and never to somebody the deployment''s configuration names as an administrator. Removing somebody already removed retires anything left and records nothing new.'
+ description: 'Remove a person from the organization. Where everybody has an organization of their own (an OpenBot whose list of organizations answers canCreate true), this ends their membership of this organization alone: they lose its Bots and conversations from their next request, and their account, sessions, API keys, their own organization and any other they belong to are unchanged. Restoring them puts the membership back with its role and teams. Where OpenBot keeps one organization, it stops the person using OpenBot: their address can''t sign in again, and the sessions, API keys and app sign-ins they hold end at once; restoring their access lets them sign in again. Either way they keep their record and their history, and the credentials they connected here are retired. Only an administrator may do this, never to themselves, never to somebody the deployment''s configuration names as an administrator, and never to the organization''s owner. Removing somebody already removed retires anything left and records nothing new.'
security:
- webSession: []
- appOAuth:
@@ -821,7 +836,7 @@ paths:
- People
operationId: restorePersonAccess
summary: Give a person their access back
- description: 'Let a removed person sign in again. What ended when they were removed stays ended: they sign in afresh and make new API keys. Only an administrator may do this. Restoring somebody who was never removed changes nothing and records nothing.'
+ description: 'Give a removed person their access back. Where everybody has an organization of their own, this puts back their membership of this organization with the role and teams it had; their sessions and API keys, which were never ended, work here again from their next request. Where OpenBot keeps one organization, it lets them sign in again, and what ended when they were removed stays ended: they sign in afresh and make new API keys. Only an administrator may do this. Restoring somebody who was never removed changes nothing and records nothing.'
security:
- webSession: []
- appOAuth:
@@ -1188,7 +1203,7 @@ paths:
- API keys
operationId: createApiKey
summary: Make an API key
- description: 'Make an API key that acts as the person, inside this organization, on the API only. The key itself is in this answer and never again: OpenBot keeps only a hash of it. Only the person themselves may make one, signed in to OpenBot: a key can never make another key, and neither can an app''s sign-in. A key ends when it expires, when it is deleted, or when an administrator removes the person.'
+ description: 'Make an API key that acts as the person, in every organization they are a member of, on the API. The key itself is in this answer and never again: OpenBot keeps only a hash of it. Only the person themselves may make one, signed in to OpenBot: a key can never make another key, and neither can an app''s sign-in. A key ends when it expires, when it is deleted, or when an administrator removes the person.'
security:
- webSession: []
parameters:
@@ -1673,7 +1688,7 @@ paths:
- Organization settings
operationId: getDeployment
summary: Read what this OpenBot offers
- description: 'Return what this OpenBot offers and how people sign in to it: the edition, the features the apps draw, and the sign-in options. Anybody may read it, signed in or not, because the sign-in screen reads it first. It names no identity provider and no version: only whether single sign-on is set up and required.'
+ description: 'Return what this OpenBot offers and how people sign in to it: the edition, the features the apps draw, and the sign-in options. Anybody may read it, signed in or not, because the sign-in screen reads it first. Signed in, it is answered in an organization the caller is a member of, and an organization they are not in, the organization `default` included, answers exactly as one that does not exist. Nobody signed in reads it in the organization `default`. It names no identity provider and no version: only whether single sign-on is set up and required.'
x-openbot-singleton: true
security:
- {}
@@ -1704,7 +1719,7 @@ paths:
- Organization settings
operationId: getOrganizationSettings
summary: Read the organization's settings
- description: 'Return the settings an administrator sets for everybody: single sign-on, recording computer actions, stopping idle computers, the model and app allowlists, sharing learned skills, check-ins a day and choosing a model. Beside them, read only, what an administrator needs to set them: the model OpenBot runs on, the directory groups, the apps an allowlist can name, the hosts every computer may reach, and whether SCIM and OpenTelemetry are set up. Only an administrator may read them.'
+ description: 'Return the settings the organization''s administrators set for its members: single sign-on, recording computer actions, stopping idle computers, the model and app allowlists, sharing learned skills, check-ins a day and choosing a model. Each organization has its own, and a new one starts with OpenBot''s defaults. Beside them, read only, what an administrator needs to set them: the model OpenBot runs on, the directory groups of the organization''s members, the apps an allowlist can name, the hosts every computer may reach, and whether SCIM and OpenTelemetry are set up. Only an administrator of the organization may read them.'
x-openbot-singleton: true
security:
- webSession: []
@@ -1739,7 +1754,7 @@ paths:
- Organization settings
operationId: updateOrganizationSettings
summary: Change the organization's settings
- description: Change the settings sent and keep the rest. Each change is recorded on the audit trail with what it was before. Requiring single sign-on needs an identity provider registered first, and signs out everybody who signed in another way, apart from the administrators the deployment's configuration names and the caller. Only an administrator may change them.
+ description: 'Change the settings sent and keep the rest. Each change is recorded on the audit trail with what it was before. Requiring single sign-on needs an identity provider registered first, and signs out everybody who signed in another way, apart from the administrators the deployment''s configuration names and the caller. Requiring single sign-on applies to signing in to the whole OpenBot, so it is set only in the organization `default`: sending ssoRequired in any other organization answers 409. Only an administrator of the organization may change them.'
security:
- webSession: []
- appOAuth:
@@ -2099,7 +2114,7 @@ paths:
- Capabilities
operationId: getPersonCapabilities
summary: Read what a person may do
- description: Return each permission switch as it applies to one person, so the apps hide what they may not use. The caller reads their own, as me; an administrator reads anybody's. enforced is false where the deployment keeps no switches and every default applies.
+ description: Return each permission switch as it applies to one person, so the apps hide what they may not use. The caller reads their own, as me; an administrator of the organization reads any member's. enforced is false where this OpenBot keeps no switches and every default applies.
x-openbot-singleton: true
security:
- webSession: []
@@ -2140,7 +2155,7 @@ paths:
- Capabilities
operationId: stopPersonComputers
summary: Stop a person's computers
- description: Stop every Bot computer running for one person now, and record it on the audit trail. Their Bots start a computer again when they next need one. Only an administrator may do this.
+ description: Stop the computers of the organization's Bots that one person owns, now, and record it on the audit trail. Their Bots start a computer again when they next need one. A person's own computer is stopped only from the organization `default`. A person who is not a member of the organization is not found (PERSON_NOT_FOUND). Only an administrator of the organization may do this.
security:
- webSession: []
- appOAuth:
@@ -2421,7 +2436,7 @@ paths:
- Organization settings
operationId: getModelUsage
summary: Read which models Bots ran on
- description: Return which models Bots ran on over the last days, with how many runs, refusals and people each had, and the newest 50 runs. Only an administrator may read it.
+ description: Return which models the organization's Bots ran on over the last days, with how many runs, refusals and people each had, and the newest 50 runs. Only an administrator of the organization may read it.
x-openbot-singleton: true
security:
- webSession: []
@@ -2470,7 +2485,7 @@ paths:
- Organization settings
operationId: listComputerActions
summary: List recorded computer actions
- description: Return one page of the actions recorded on Bot computers while recording computer actions is on, newest first. Records are kept for actionRecordRetentionDays. Only an administrator may read them. A missing cursor starts at the newest and nextCursor null ends the list.
+ description: Return one page of the actions recorded on the organization's Bots' computers while recording computer actions is on, newest first. Records are kept for actionRecordRetentionDays. Only an administrator of the organization may read them. A missing cursor starts at the newest and nextCursor null ends the list.
security:
- webSession: []
- appOAuth:
@@ -2594,7 +2609,7 @@ paths:
- Conversations
operationId: createConversationJoinToken
summary: Get a token to watch a conversation live
- description: 'Make a join token for the conversation''s thread, and say where to use it. The token opens the threadStream channel of api/asyncapi.yaml: a WebSocket that replays the Bot''s runs in the conversation, a run in progress from its start, and then carries on live. The token works once and for about half a minute, so ask for a new one for every connection, and again to reconnect. Only a person in the conversation may have one, and it opens the thread they see there and no other. A conversation no Bot has run in yet has nothing to join.'
+ description: 'Make a join token for the conversation''s thread, and say where to use it. The token opens the threadStream channel of api/asyncapi.yaml: a WebSocket that replays the Bot''s runs in the conversation, a run in progress from its start, and then carries on live. The token works once and for about half a minute, so ask for a new one for every connection, and again to reconnect. Only a person in the conversation may have one, and it opens the thread they see there and no other. A conversation no Bot has run in yet has nothing to join (409). Where realtime.clientUrl is on this server, open it with the same credential that made the token: the session, an app''s access token, or an API key, as Authorization: Bearer or x-api-key. So a script that holds only an API key can watch a conversation live.'
security:
- webSession: []
- appOAuth:
@@ -3945,7 +3960,7 @@ paths:
- Credentials
operationId: listCredentials
summary: List the credentials in the vault
- description: 'Return one page of the credentials the vault keeps, live and revoked, oldest first. A credential says what it is for and whether it is live, and never holds its secret: nothing in the API reads a secret back out. Only an administrator may list them. A missing cursor starts at the first page and nextCursor null ends the list.'
+ description: 'Return one page of the credentials the organization''s vault keeps, live and revoked, oldest first. Each organization has its own vault, and another organization''s credentials are never listed. A credential says what it is for and whether it is live, and never holds its secret: nothing in the API reads a secret back out. Only an administrator of the organization may list them. A missing cursor starts at the first page and nextCursor null ends the list.'
security:
- webSession: []
- appOAuth:
@@ -3986,7 +4001,7 @@ paths:
- Credentials
operationId: createCredential
summary: Add a credential to the vault
- description: 'Encrypt a secret and keep it in the vault under one key: a kind, a provider and a key id. A key holds one live credential, so adding one for a key that already has one replaces it, and the one it replaces is revoked in the same write. A model key sent without a key id is filed under the name OpenBot''s own Bots read (getModelKey). The secret is write-only: no answer includes it, now or later. Recorded on the audit trail. Only an administrator may add one.'
+ description: 'Encrypt a secret and keep it in the organization''s vault under one key: a kind, a provider and a key id. A key holds one live credential, so adding one for a key that already has one replaces it, and the one it replaces is revoked in the same write. A model key sent without a key id is filed under the name OpenBot''s own Bots read (getModelKey). The secret is write-only: no answer includes it, now or later. Recorded on the audit trail. Only an administrator of the organization may add one.'
security:
- webSession: []
- appOAuth:
@@ -4044,7 +4059,7 @@ paths:
- Credentials
operationId: revokeCredential
summary: Revoke a credential
- description: Stop a live credential being used, and keep its record. Nothing reads a revoked credential again. Recorded on the audit trail. Only an administrator may revoke one. One that does not exist, or is revoked already, is not found.
+ description: Stop a live credential being used, and keep its record. Nothing reads a revoked credential again. Recorded on the audit trail. Only an administrator of the organization may revoke one. One that does not exist, is in another organization's vault, or is revoked already, is not found.
security:
- webSession: []
- appOAuth:
@@ -4089,7 +4104,7 @@ paths:
- Credentials
operationId: getModelKey
summary: Read where the Bots find their model key
- description: Return the provider OpenBot's own Bots run on, the key id their model key is filed under in the vault, and whether a live key is kept there. Never the key. A model key added without a key id is filed here. Only an administrator may read it.
+ description: Return the provider OpenBot's own Bots run on, the key id their model key is filed under in the organization's vault, and whether a live key is kept there. Never the key. A model key added without a key id is filed here. Only an administrator of the organization may read it.
x-openbot-singleton: true
security:
- webSession: []
@@ -4269,7 +4284,7 @@ paths:
- Apps
operationId: listApps
summary: List the apps added here
- description: 'Return one page of the apps this OpenBot has added for its Bots: the ones from its catalogue, the ones added from the app directory, and servers added by their address. Each app comes with the actions it offers and the Bots that may use each one. Anybody signed in may read them. Ordered by title, ignoring case, then by id. A missing cursor starts at the first page and nextCursor null ends the list.'
+ description: 'Return one page of the apps the organization has added for its Bots: the ones from OpenBot''s catalogue, the ones added from the app directory, and servers added by their address. Each organization has its own apps, and an app added in one is not in another. Each app comes with the actions it offers and the Bots that may use each one. Any member of the organization may read them. Ordered by title, ignoring case, then by id. A missing cursor starts at the first page and nextCursor null ends the list.'
security:
- webSession: []
- appOAuth:
@@ -4533,7 +4548,7 @@ paths:
- Apps
operationId: deleteApp
summary: Remove an app
- description: Remove an app for everybody. Every person's connection to it is ended, at the app's own service too, every Bot stops being able to use its actions, and a server's key is retired. Recorded on the audit trail. Removing can stop partway when the service behind the app doesn't answer. The app then stays, and removing it again is safe and finishes the job. Routines can't be removed. Only an administrator may.
+ description: Remove an app for everybody in the organization. Every member's connection to it is ended, at the app's own service too, every Bot stops being able to use its actions, and a server's key is retired. Recorded on the audit trail. Removing can stop partway when the service behind the app doesn't answer. The app then stays, and removing it again is safe and finishes the job. Routines can't be removed. Only an administrator of the organization may.
security:
- webSession: []
- appOAuth:
@@ -4615,7 +4630,7 @@ paths:
- Apps
operationId: setAppAccountMode
summary: Choose whose account an app acts in
- description: 'Choose whose account an app from the directory acts in: each person''s own (personal), or one account OpenBot holds for everybody (shared). Every account the switch leaves behind is ended at the app''s service first. Nothing changes unless all of them ended, and the problem''s problems then names each account that didn''t. Switching to shared gives each Bot that uses the app an approval, the one in approvals or its default, and makes the app ask before every action that changes something. With validateOnly true nothing changes, and the answer says what the switch would end and approve. Choosing the mode an app is already in puts back anything that mode needs and is missing. Recorded on the audit trail. Only an administrator may.'
+ description: 'Choose whose account an app from the directory acts in: each person''s own (personal), or one account OpenBot holds for everybody in the organization (shared). Every account the switch leaves behind is ended at the app''s service first. Nothing changes unless all of them ended, and the problem''s problems then names each account that didn''t. Switching to shared gives each Bot that uses the app an approval, the one in approvals or its default, and makes the app ask before every action that changes something. With validateOnly true nothing changes, and the answer says what the switch would end and approve. Choosing the mode an app is already in puts back anything that mode needs and is missing. Recorded on the audit trail. Only an administrator may.'
security:
- webSession: []
- appOAuth:
@@ -5463,7 +5478,7 @@ paths:
- Connections
operationId: getSharedConnection
summary: Read an app's shared account
- description: 'Return the one account an app in Shared mode acts as for everybody: whether it is connected, who connected it, and the app''s own name for the account. Anybody signed in may read it. Not found when the app is connected by each person instead, as getConnection reads.'
+ description: 'Return the one account an app in Shared mode acts as for everybody in the organization: whether it is connected, who connected it, and the app''s own name for the account. Each organization connects its own, and one organization''s shared account is never used in another. Any member of the organization may read it. Not found when the app is connected by each person instead, as getConnection reads.'
x-openbot-singleton: true
security:
- webSession: []
@@ -5504,7 +5519,7 @@ paths:
- Connections
operationId: connectSharedApp
summary: Start connecting an app's shared account
- description: 'Start connecting the one account an app in Shared mode acts as for everybody, and say what happens next, as connectApp does: consent answers the address of the app''s sign-in page, form answers the boxes to fill in, connected means it is connected already. The person comes back to the app''s page, where confirmSharedConnection checks the result. Where an app connects once, a shared account already connected is a conflict: disconnect it first. Only an administrator may connect it. The address and the values are never logged.'
+ description: 'Start connecting the one account an app in Shared mode acts as for everybody in the organization, and say what happens next, as connectApp does: consent answers the address of the app''s sign-in page, form answers the boxes to fill in, connected means it is connected already. The person comes back to the app''s page, where confirmSharedConnection checks the result. Where an app connects once, a shared account already connected is a conflict: disconnect it first. Only an administrator of the organization may connect it. The address and the values are never logged.'
security:
- webSession: []
- appOAuth:
@@ -6339,6 +6354,98 @@ paths:
$ref: '#/components/responses/AppDirectoryUnavailable'
default:
$ref: '#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/apps/{appId}/team-grants:
+ parameters:
+ - $ref: '#/components/parameters/OrganizationId'
+ - $ref: '#/components/parameters/AppId'
+ get:
+ tags:
+ - Bot grants
+ operationId: getAppTeamGrants
+ summary: Read the teams the app is granted to
+ description: Return the teams the app is granted to, by id. A person in one of those teams, or in a team beneath one, may give the app to a Bot they own without an access request, and the Bot may use it only while they stay in such a team; nobody else in the organization may give it to their own Bot. Only an admin of the organization may read them.
+ x-openbot-singleton: true
+ security:
+ - webSession: []
+ - appOAuth:
+ - bot-grants:read
+ - apiKey: []
+ responses:
+ '200':
+ description: The teams the app is granted to.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/AppTeamGrants'
+ examples:
+ granted:
+ $ref: '#/components/examples/AppTeamGrantsExample'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/AppOrTeamNotFound'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ put:
+ tags:
+ - Bot grants
+ operationId: replaceAppTeamGrants
+ summary: Grant an app to teams
+ description: Grant the app to exactly these teams of the organization, taking it from any team left out. An empty list takes it from every team. A person in one of those teams, or in a team beneath one, may give the app to a Bot they own without an access request, and the Bot may use it only while they stay in such a team; nobody else in the organization may give it to their own Bot. A team of another organization is not found. Only an admin of the organization may do this. Recorded on the audit trail.
+ security:
+ - webSession: []
+ - appOAuth:
+ - bot-grants:write
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/AppTeamGrantsInput'
+ examples:
+ oneTeam:
+ value:
+ teams:
+ - Tm4Qx8LpV2nWc7RbY1sKd0Ze
+ responses:
+ '200':
+ description: The teams the app is now granted to.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/AppTeamGrants'
+ examples:
+ granted:
+ $ref: '#/components/examples/AppTeamGrantsExample'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/AppOrTeamNotFound'
+ '409':
+ $ref: '#/components/responses/IdempotencyConflict'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
/api/v2/organizations/{organizationId}/people/{personId}/giveable-apps:
parameters:
- $ref: '#/components/parameters/OrganizationId'
@@ -6390,7 +6497,7 @@ paths:
- App access requests
operationId: listAppAccessRequests
summary: List requests for apps
- description: 'Return one page of the requests waiting for an administrator: all of them for an administrator, and only their own for anybody else. appId narrows them to one app. Newest first, and by id among requests made at the same moment. A missing cursor starts at the first page and nextCursor null ends the list.'
+ description: 'Return one page of the organization''s requests waiting for an administrator: all of them for an administrator of the organization, and only their own for anybody else. appId narrows them to one app. Newest first, and by id among requests made at the same moment. A missing cursor starts at the first page and nextCursor null ends the list.'
security:
- webSession: []
- appOAuth:
@@ -6649,7 +6756,7 @@ paths:
- Components
operationId: listComponents
summary: List components
- description: 'Return one page of the components Bots draw in conversations: charts, cards and the ones an admin wrote in Playground. An admin sees every component with its draft, the Bots held back from it and the data it may read. Anybody else sees the published ones only, and those fields are null. kind=playground lists only the components written in Playground, each published one with the source a conversation draws it from. Ordered by kind, then title, then name. A missing cursor starts at the first page and nextCursor null ends the list.'
+ description: 'Return one page of the components the organization''s Bots draw in conversations: charts, cards and the ones an admin wrote in Playground. Each organization has its own: what a component tells the model, whether it is published, which Bots may draw it and which data it may read are decided in one organization and change nothing in another. An admin of the organization sees every component with its draft, the Bots held back from it and the data it may read. Anybody else sees the published ones only, and those fields are null. kind=playground lists only the components written in Playground, each published one with the source a conversation draws it from. Ordered by kind, then title, then name. A missing cursor starts at the first page and nextCursor null ends the list.'
security:
- webSession: []
- appOAuth:
@@ -6692,7 +6799,7 @@ paths:
- Components
operationId: announceComponents
summary: Announce the components the app can draw
- description: 'Tell OpenBot which components this version of the app can draw. A component OpenBot has not seen before is added and published, so every Bot can draw it at once. One it already has is left exactly as it is: what it tells the model, whether it is published and who may use it were decided here. A description nobody here has edited follows the one this version of OpenBot ships. In OpenBot Personal a component is also given the data it reads. Anybody signed in may announce, and the web app does it on every load. The whole list is refused if one entry is missing a field.'
+ description: 'Tell OpenBot which components this version of the app can draw. A component the organization has not seen before is added and published, so every one of its Bots can draw it at once. One it already has is left exactly as it is: what it tells the model, whether it is published and who may use it were decided here. A description nobody here has edited follows the one this version of OpenBot ships. In OpenBot Personal a component is also given the data it reads. Anybody signed in may announce, and the web app does it on every load. The whole list is refused if one entry is missing a field or has a name that starts with @.'
security:
- webSession: []
- appOAuth:
@@ -6720,7 +6827,7 @@ paths:
description: Show how many actions each Bot took recently.
responses:
'200':
- description: The components this announcement added. Empty when OpenBot had them all.
+ description: The components this announcement added. Empty when the organization had them all.
headers:
Cache-Control:
$ref: '#/components/headers/PrivateNoStore'
@@ -7335,7 +7442,7 @@ paths:
- Skills
operationId: listSkills
summary: List skills
- description: 'Return one page of the skills the caller can see: the organization''s and their own. An admin sees everybody''s. Ordered by title, then slug. A missing cursor starts at the first page and nextCursor null ends the list.'
+ description: 'Return one page of the skills the caller can see: their own, the ones granted to a team they are in, and the organization''s that are granted to no team. An organization''s skill granted to teams is listed only to those teams'' people. An admin of the organization sees every skill. Another organization''s skills are never listed. Ordered by title, then slug. A missing cursor starts at the first page and nextCursor null ends the list.'
security:
- webSession: []
- appOAuth:
@@ -7378,7 +7485,7 @@ paths:
- Skills
operationId: getSkill
summary: Read a skill
- description: 'Return one skill the caller can see: the organization''s or their own. An admin can read anybody''s. Somebody else''s skill is not found.'
+ description: Return one skill the caller can see, as the list shows them. An admin can read any. One the caller can't see is not found.
security:
- webSession: []
- appOAuth:
@@ -7493,6 +7600,98 @@ paths:
$ref: '#/components/responses/ServerError'
default:
$ref: '#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/skills/{skillId}/team-grants:
+ parameters:
+ - $ref: '#/components/parameters/OrganizationId'
+ - $ref: '#/components/parameters/SkillId'
+ get:
+ tags:
+ - Skills
+ operationId: getSkillTeamGrants
+ summary: Read the teams the skill is granted to
+ description: Return the teams the skill is granted to, by id. A person in one of those teams, or in a team beneath one, may put the skill on a Bot they own, and the Bot is offered it only while they stay in such a team. Only an admin of the organization may read them.
+ x-openbot-singleton: true
+ security:
+ - webSession: []
+ - appOAuth:
+ - skills:read
+ - apiKey: []
+ responses:
+ '200':
+ description: The teams the skill is granted to.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SkillTeamGrants'
+ examples:
+ granted:
+ $ref: '#/components/examples/SkillTeamGrantsExample'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/SkillOrTeamNotFound'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ put:
+ tags:
+ - Skills
+ operationId: replaceSkillTeamGrants
+ summary: Grant a skill to teams
+ description: Grant the skill to exactly these teams of the organization, taking it from any team left out. An empty list takes it from every team. A person in one of those teams, or in a team beneath one, may put the skill on a Bot they own, and the Bot is offered it only while they stay in such a team. A team of another organization is not found. Only an admin of the organization may do this. Recorded on the audit trail.
+ security:
+ - webSession: []
+ - appOAuth:
+ - skills:write
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SkillTeamGrantsInput'
+ examples:
+ oneTeam:
+ value:
+ teams:
+ - Tm4Qx8LpV2nWc7RbY1sKd0Ze
+ responses:
+ '200':
+ description: The teams the skill is now granted to.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SkillTeamGrants'
+ examples:
+ granted:
+ $ref: '#/components/examples/SkillTeamGrantsExample'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/SkillOrTeamNotFound'
+ '409':
+ $ref: '#/components/responses/IdempotencyConflict'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
/api/v2/organizations/{organizationId}/people/{personId}/devices:
parameters:
- $ref: '#/components/parameters/OrganizationId'
@@ -7632,7 +7831,7 @@ paths:
- Destinations
operationId: listDestinations
summary: List where a person's Bots reach them
- description: 'Return one page of the places outside OpenBot a person continues their conversations with Bots: a Slack or Microsoft Teams chat, or a phone number for text messages, each tied to one conversation with one Bot. The first connected first. Only the person themselves may list them; there is no administrator view. A missing cursor starts at the first page and nextCursor null ends the list.'
+ description: 'Return one page of the places outside OpenBot a person continues their conversations with Bots: a Slack or Microsoft Teams chat, or a phone number for text messages, each tied to one conversation with one Bot. A Slack account, a Teams account or a phone number is connected in one organization at a time: connecting one that is connected in another organization answers 400 until it is disconnected there. The first connected first. Only the person themselves may list them; there is no administrator view. A missing cursor starts at the first page and nextCursor null ends the list.'
security:
- webSession: []
- appOAuth:
@@ -8817,7 +9016,7 @@ paths:
- Check-ins
operationId: getCheckInUsage
summary: Read how check-ins are going
- description: 'Return, per Bot, over the last 7 or 30 days: how its check-ins ended, what they raised, what people did with it and how many notices carried it, with the daily limit in force. Counts only: no item''s title, source or person. Only an administrator may read it.'
+ description: 'Return, per Bot in the organization, over the last 7 or 30 days: how its check-ins ended, what they raised, what people did with it and how many notices carried it, with the organization''s daily limit in force. Counts only: no item''s title, source or person. Only an administrator of the organization may read it.'
x-openbot-singleton: true
security:
- webSession: []
@@ -9809,7 +10008,7 @@ paths:
- Organizations
operationId: listOrganizations
summary: List the caller's organizations
- description: Return one page of the organizations the caller is a member of, the one they joined first at the top, each with the caller's role in it. active marks the one the caller's session is working in, which is where every address outside /api/v2 reads and writes; a request signed in with an API key or an app's token has no session, so none is active. To work in another one, set it as the session's active organization (POST /api/auth/organization/set-active). A missing cursor starts at the first page and nextCursor null ends the list.
+ description: 'Return one page of the organizations the caller is a member of, the one they joined first at the top, each with the caller''s role in it. active marks the one the caller''s session is working in, which is where every address outside /api/v2 reads and writes. A request signed in with an API key has no session, so none is active. An app''s token has no session either: for it, active marks the organization its OpenBot-Organization header names, or the caller''s own when it sends none. The header is checked against the caller''s membership, as on every address that names no organization, so one they are not in answers not found. A session and an API key ignore it. To work in another one, set it as the session''s active organization (POST /api/auth/organization/set-active). Made with an app''s token, that call checks that the caller is a member, stores nothing and answers the organization. A missing cursor starts at the first page and nextCursor null ends the list.'
security:
- webSession: []
- appOAuth:
@@ -9818,6 +10017,14 @@ paths:
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Cursor'
+ - name: OpenBot-Organization
+ in: header
+ required: false
+ description: 'For a request signed in with an app''s token: the organization it works in, by id or slug, which the list marks active. Without it the caller''s own is active. One the caller is not a member of answers not found, and one that is not a single id or slug 400. Ignored for a session and an API key.'
+ schema:
+ type: string
+ minLength: 1
+ maxLength: 200
responses:
'200':
description: One page of organizations.
@@ -9837,6 +10044,8 @@ paths:
$ref: '#/components/responses/Unauthenticated'
'403':
$ref: '#/components/responses/Forbidden'
+ '404':
+ $ref: '#/components/responses/OrganizationNotFound'
'500':
$ref: '#/components/responses/ServerError'
default:
@@ -9846,7 +10055,7 @@ paths:
- Organizations
operationId: createOrganization
summary: Create an organization
- description: 'Create an organization with the caller as its owner. It starts with no Bots and no conversations. Who may create one is the deployment''s choice: its admins (the admins of `default`) unless it lets anybody signed in. Without a slug, one is made from the name. The caller''s session keeps working where it was. A repeated request with the same Idempotency-Key and body returns the first result.'
+ description: Create an organization with the caller as its owner. It starts with what a fresh install starts with, its starter Bots included, and no conversations. Everybody already has an organization of their own, made when they first signed in; this is for making another, which anybody signed in may do where OpenBot keeps more than one. Without a slug, one is made from the name. The caller's session keeps working where it was. A repeated request with the same Idempotency-Key and body returns the first result.
security:
- webSession: []
- appOAuth:
@@ -9883,7 +10092,7 @@ paths:
'401':
$ref: '#/components/responses/Unauthenticated'
'403':
- $ref: '#/components/responses/AdminOnly'
+ $ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/OrganizationConflict'
'500':
@@ -9934,12 +10143,194 @@ paths:
$ref: '#/components/responses/ServerError'
default:
$ref: '#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/profile:
+ parameters:
+ - $ref: '#/components/parameters/OrganizationId'
+ patch:
+ tags:
+ - Organizations
+ operationId: updateOrganization
+ summary: Rename an organization
+ description: Give the organization a new name. Its id and its slug stay as they are, so every address that names it keeps working. An organization OpenBot named after its person stops following what that person is called once it has been renamed. Only an owner or an admin of this organization can. A repeated request with the same Idempotency-Key and body returns the first result.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:write
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateOrganizationRequest'
+ examples:
+ renamed:
+ value:
+ name: Acme Research Lab
+ responses:
+ '200':
+ description: The organization, renamed.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OrganizationResponse'
+ examples:
+ renamed:
+ $ref: '#/components/examples/RenamedOrganization'
+ '400':
+ $ref: '#/components/responses/InvalidOrganization'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/OrganizationNotFound'
+ '409':
+ $ref: '#/components/responses/IdempotencyConflict'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/members/{personId}:
+ parameters:
+ - $ref: '#/components/parameters/OrganizationId'
+ - $ref: '#/components/parameters/PersonId'
+ patch:
+ tags:
+ - Organizations
+ operationId: updateOrganizationMember
+ summary: Change a member's role
+ description: 'Give a member of the organization another role. An owner or an admin changes anybody between admin and member. Only an owner makes somebody an owner, or changes an owner''s role, their own included, and the organization always keeps an owner: the last one cannot step down. A person''s own organization keeps exactly its one owner. The members list says which roles the caller may give each member, as assignableRoles. A repeated request with the same Idempotency-Key and body returns the first result.'
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:write
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateOrganizationMemberRequest'
+ examples:
+ owner:
+ value:
+ role: owner
+ responses:
+ '200':
+ description: The member, with their new role.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OrganizationMemberResponse'
+ examples:
+ owner:
+ $ref: '#/components/examples/PromotedOrganizationMember'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/PersonNotFound'
+ '409':
+ $ref: '#/components/responses/OwnerStays'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ delete:
+ tags:
+ - Organizations
+ operationId: removeOrganizationMember
+ summary: Remove a member, or leave an organization
+ description: End somebody's membership of the organization. An owner or an admin of it can remove anybody whose membership can end, and any such member can leave by naming themselves or `me`. The owner stays, so nobody leaves their own organization, and so does somebody this OpenBot's settings keep as an admin of it. The person keeps their account and their other organizations, and what they made here stays here. Removing somebody who is not a member answers the same as removing one.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:write
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/IdempotencyKey'
+ responses:
+ '204':
+ description: They are not a member.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/OrganizationNotFound'
+ '409':
+ $ref: '#/components/responses/OwnerStays'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/invitations:
+ parameters:
+ - $ref: '#/components/parameters/OrganizationId'
+ get:
+ tags:
+ - Organizations
+ operationId: listOrganizationInvitations
+ summary: List the invitations an organization has sent
+ description: 'Return one page of the organization''s invitations that have not been accepted or canceled, the newest first: the ones still waiting, the ones that expired and the ones that were declined. Only an owner or an admin of this organization can read it. A missing cursor starts at the first page and nextCursor null ends the list.'
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:read
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/Limit'
+ - $ref: '#/components/parameters/Cursor'
+ responses:
+ '200':
+ description: One page of invitations.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OrganizationInvitationPage'
+ examples:
+ lastPage:
+ $ref: '#/components/examples/OrganizationInvitationPageLast'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/OrganizationNotFound'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
post:
tags:
- Organizations
- operationId: addOrganizationMember
- summary: Add a person to an organization
- description: Make somebody who already has an account here a member of the organization, by their email address, with a role. Only an owner or an admin of this organization can. A repeated request with the same Idempotency-Key and body returns the first result.
+ operationId: createOrganizationInvitation
+ summary: Invite somebody to an organization
+ description: 'Invite the person with this email address to join the organization with a role. They need no account yet: the invitation waits for whoever signs in with that address, and they see it in OpenBot then. Where OpenBot can send email, it also emails them; delivery says which happened, so the inviter knows whether to pass the link on themselves. The invitation lasts seven days. Inviting an address again after its invitation expired or was declined starts a new one. Only an owner or an admin of this organization can. A repeated request with the same Idempotency-Key and body returns the first result.'
security:
- webSession: []
- appOAuth:
@@ -9952,7 +10343,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/AddOrganizationMemberRequest'
+ $ref: '#/components/schemas/CreateOrganizationInvitationRequest'
examples:
member:
value:
@@ -9960,32 +10351,567 @@ paths:
role: member
responses:
'201':
- description: The person is now a member.
+ description: The invitation was made.
headers:
Cache-Control:
$ref: '#/components/headers/PrivateNoStore'
Location:
- description: The organization's members.
+ description: The organization's invitations.
schema:
type: string
- example: /api/v2/organizations/Jq3xT9mLw2Vb8RnC5sYd0fKe/members
+ example: /api/v2/organizations/Jq3xT9mLw2Vb8RnC5sYd0fKe/invitations
content:
application/json:
schema:
- $ref: '#/components/schemas/OrganizationMemberResponse'
+ $ref: '#/components/schemas/OrganizationInvitationResponse'
examples:
- added:
- $ref: '#/components/examples/AddedOrganizationMember'
+ invited:
+ $ref: '#/components/examples/CreatedOrganizationInvitation'
+ '400':
+ $ref: '#/components/responses/InvalidOrganizationInvitation'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/OrganizationNotFound'
+ '409':
+ $ref: '#/components/responses/OrganizationInvitationConflict'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/invitations/{invitationId}:
+ parameters:
+ - $ref: '#/components/parameters/OrganizationId'
+ - $ref: '#/components/parameters/InvitationId'
+ delete:
+ tags:
+ - Organizations
+ operationId: cancelOrganizationInvitation
+ summary: Cancel an invitation
+ description: Take back an invitation the organization sent, whatever state it is in. It leaves the organization's list and the invited person's. Only an owner or an admin of this organization can.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:write
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/IdempotencyKey'
+ responses:
+ '204':
+ description: The invitation is canceled.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/OrganizationOrInvitationNotFound'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ /api/v2/people/me/invitations:
+ get:
+ tags:
+ - Organizations
+ operationId: listInvitations
+ summary: List the caller's invitations
+ description: Return one page of the invitations sent to the caller's email address that they have not answered, the newest first, each with the organization and who invited them. One that ran out of time is listed as expired until it is canceled or replaced. A missing cursor starts at the first page and nextCursor null ends the list.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:read
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/Limit'
+ - $ref: '#/components/parameters/Cursor'
+ responses:
+ '200':
+ description: One page of invitations.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/InvitationPage'
+ examples:
+ lastPage:
+ $ref: '#/components/examples/InvitationPageLast'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/Forbidden'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ /api/v2/people/me/invitations/{invitationId}:
+ parameters:
+ - $ref: '#/components/parameters/InvitationId'
+ get:
+ tags:
+ - Organizations
+ operationId: getInvitation
+ summary: Read one of the caller's invitations
+ description: Return an invitation sent to the caller's email address, in whatever state it is in, so the page a link opens can say what happened to it. An invitation sent to another address answers as one that does not exist.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:read
+ - apiKey: []
+ responses:
+ '200':
+ description: The invitation.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/InvitationResponse'
+ examples:
+ waiting:
+ $ref: '#/components/examples/WaitingInvitation'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/Forbidden'
+ '404':
+ $ref: '#/components/responses/InvitationNotFound'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ /api/v2/people/me/invitations/{invitationId}/accept:
+ parameters:
+ - $ref: '#/components/parameters/InvitationId'
+ post:
+ tags:
+ - Organizations
+ operationId: acceptInvitation
+ summary: Accept an invitation
+ description: Join the organization the invitation is for, with the role it offers. The caller's session keeps working where it was; switch to the new organization to work in it. An invitation that expired, was canceled or was already answered is refused in words. A repeated request with the same Idempotency-Key returns the first result.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:write
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/IdempotencyKey'
+ responses:
+ '200':
+ description: The caller is now a member of the organization.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OrganizationResponse'
+ examples:
+ joined:
+ $ref: '#/components/examples/JoinedOrganization'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/Forbidden'
+ '404':
+ $ref: '#/components/responses/InvitationNotFound'
+ '409':
+ $ref: '#/components/responses/InvitationNotWaiting'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ /api/v2/people/me/invitations/{invitationId}/decline:
+ parameters:
+ - $ref: '#/components/parameters/InvitationId'
+ post:
+ tags:
+ - Organizations
+ operationId: declineInvitation
+ summary: Decline an invitation
+ description: Turn the invitation down. It leaves the caller's list, and the organization sees that it was declined. A repeated request with the same Idempotency-Key returns the first result.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:write
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/IdempotencyKey'
+ responses:
+ '204':
+ description: The invitation is declined.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/Forbidden'
+ '404':
+ $ref: '#/components/responses/InvitationNotFound'
+ '409':
+ $ref: '#/components/responses/InvitationNotWaiting'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/teams:
+ parameters:
+ - $ref: '#/components/parameters/OrganizationId'
+ get:
+ tags:
+ - Teams
+ operationId: listTeams
+ summary: List an organization's teams
+ description: Return one page of the organization's teams, in the order they were created. Any member of the organization can read it. Each team says the caller's own role in it and whether the caller may manage it. A missing cursor starts at the first page and nextCursor null ends the list.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:read
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/Limit'
+ - $ref: '#/components/parameters/Cursor'
+ responses:
+ '200':
+ description: One page of teams.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TeamPage'
+ examples:
+ lastPage:
+ $ref: '#/components/examples/TeamPageLast'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/Forbidden'
+ '404':
+ $ref: '#/components/responses/OrganizationNotFound'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ post:
+ tags:
+ - Teams
+ operationId: createTeam
+ summary: Create a team
+ description: Create a team in the organization. Only an owner or an admin of the organization can. A team's name is unique in its organization, whatever its case. A team may sit under a parent team, and then its members can use everything granted to the parent as well. A repeated request with the same Idempotency-Key and body returns the first result.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:write
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateTeamRequest'
+ examples:
+ named:
+ value:
+ name: Sales
+ description: Everybody who sells.
+ responses:
+ '201':
+ description: The team was created.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ Location:
+ description: The new team.
+ schema:
+ type: string
+ example: /api/v2/organizations/default/teams/Tm4Qx8LpV2nWc7RbY1sKd0Ze
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TeamResponse'
+ examples:
+ created:
+ $ref: '#/components/examples/CreatedTeam'
'400':
- $ref: '#/components/responses/InvalidOrganizationMember'
+ $ref: '#/components/responses/InvalidTeam'
'401':
$ref: '#/components/responses/Unauthenticated'
'403':
$ref: '#/components/responses/AdminOnly'
'404':
- $ref: '#/components/responses/OrganizationOrPersonNotFound'
+ $ref: '#/components/responses/OrganizationNotFound'
+ '409':
+ $ref: '#/components/responses/TeamConflict'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/teams/{teamId}:
+ parameters:
+ - $ref: '#/components/parameters/OrganizationId'
+ - $ref: '#/components/parameters/TeamId'
+ get:
+ tags:
+ - Teams
+ operationId: getTeam
+ summary: Read one team
+ description: Return one of the organization's teams. Any member of the organization can read it. A team of another organization is not found.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:read
+ - apiKey: []
+ responses:
+ '200':
+ description: The team.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TeamResponse'
+ examples:
+ team:
+ $ref: '#/components/examples/CreatedTeam'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/Forbidden'
+ '404':
+ $ref: '#/components/responses/TeamNotFound'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ patch:
+ tags:
+ - Teams
+ operationId: updateTeam
+ summary: Change a team
+ description: Change a team's name, its description or its parent team; a field that is absent stays as it is, and a null parent takes the team out from under its parent. An owner or an admin of the organization can, and so can one of the team's maintainers, except that only an owner or an admin changes its parent. A team that comes from the company's directory keeps the directory's name. A team can't be put under itself or under a team beneath it.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:write
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateTeamRequest'
+ examples:
+ renamed:
+ value:
+ name: Sales EMEA
+ responses:
+ '200':
+ description: The team as it now is.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TeamResponse'
+ examples:
+ changed:
+ $ref: '#/components/examples/CreatedTeam'
+ '400':
+ $ref: '#/components/responses/InvalidTeam'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/TeamForbidden'
+ '404':
+ $ref: '#/components/responses/TeamNotFound'
+ '409':
+ $ref: '#/components/responses/TeamConflict'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ delete:
+ tags:
+ - Teams
+ operationId: deleteTeam
+ summary: Delete a team
+ description: Delete a team. Its members stay in the organization and lose what was granted to the team, at once. Teams under it move up to its own parent. Only an owner or an admin of the organization can. A team that comes from the company's directory is removed there, not here. Deleting a team that is not there changes nothing.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:write
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/IdempotencyKey'
+ responses:
+ '204':
+ description: The team is gone.
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/TeamForbidden'
+ '404':
+ $ref: '#/components/responses/OrganizationNotFound'
+ '409':
+ $ref: '#/components/responses/IdempotencyConflict'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/teams/{teamId}/members:
+ parameters:
+ - $ref: '#/components/parameters/OrganizationId'
+ - $ref: '#/components/parameters/TeamId'
+ get:
+ tags:
+ - Teams
+ operationId: listTeamMembers
+ summary: List a team's members
+ description: Return one page of the people in a team, in the order they joined it. Any member of the organization can read it. People who are only in a team beneath this one are not listed. A missing cursor starts at the first page and nextCursor null ends the list.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:read
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/Limit'
+ - $ref: '#/components/parameters/Cursor'
+ responses:
+ '200':
+ description: One page of the team's members.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TeamMemberPage'
+ examples:
+ lastPage:
+ $ref: '#/components/examples/TeamMemberPageLast'
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/Forbidden'
+ '404':
+ $ref: '#/components/responses/TeamNotFound'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/teams/{teamId}/members/{memberId}:
+ parameters:
+ - $ref: '#/components/parameters/OrganizationId'
+ - $ref: '#/components/parameters/TeamId'
+ - $ref: '#/components/parameters/TeamMemberId'
+ put:
+ tags:
+ - Teams
+ operationId: putTeamMember
+ summary: Add a person to a team, or change their role in it
+ description: Put a member of the organization in the team with a role, or change the role of somebody already in it. What is granted to the team is theirs from their next request. An owner or an admin of the organization can, and so can one of the team's maintainers. A team that comes from the company's directory takes its people from the directory, so nobody is added to it here.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:write
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PutTeamMemberRequest'
+ examples:
+ member:
+ value:
+ role: member
+ responses:
+ '200':
+ description: The person as a member of the team.
+ headers:
+ Cache-Control:
+ $ref: '#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TeamMemberResponse'
+ examples:
+ added:
+ $ref: '#/components/examples/AddedTeamMember'
+ '400':
+ $ref: '#/components/responses/InvalidTeamMember'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/TeamForbidden'
+ '404':
+ $ref: '#/components/responses/TeamOrPersonNotFound'
+ '409':
+ $ref: '#/components/responses/IdempotencyConflict'
+ '500':
+ $ref: '#/components/responses/ServerError'
+ default:
+ $ref: '#/components/responses/UnexpectedError'
+ delete:
+ tags:
+ - Teams
+ operationId: removeTeamMember
+ summary: Take a person out of a team
+ description: Take a person out of the team. They stay in the organization and lose what was granted to the team from their next request. An owner or an admin of the organization can, so can one of the team's maintainers, and anybody can take themselves out. A team that comes from the company's directory takes its people from the directory, so nobody is removed from it here. Removing somebody who is not in the team changes nothing.
+ security:
+ - webSession: []
+ - appOAuth:
+ - organizations:write
+ - apiKey: []
+ parameters:
+ - $ref: '#/components/parameters/IdempotencyKey'
+ responses:
+ '204':
+ description: They are not in the team.
+ '400':
+ $ref: '#/components/responses/InvalidRequest'
+ '401':
+ $ref: '#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/TeamForbidden'
+ '404':
+ $ref: '#/components/responses/TeamNotFound'
'409':
- $ref: '#/components/responses/OrganizationMemberConflict'
+ $ref: '#/components/responses/IdempotencyConflict'
'500':
$ref: '#/components/responses/ServerError'
default:
@@ -13007,7 +13933,7 @@ paths:
- Team Bots
operationId: listTeamBots
summary: List Team Bots
- description: 'Return one page of the published Bots the caller may use or manages: their own publications, the ones published to them by name, to a group they are in or to the whole team, and the ones an administrator assigned them. An administrator sees every one. Who a Team Bot reaches (people, groups and assignments) is shown only to its owner and administrators. Ordered by name, then the Bot''s id. A missing cursor starts at the first page and nextCursor null ends the list.'
+ description: 'Return one page of the published Bots the caller may use or manages: their own publications, the ones published to them by name, to a group or team they are in or to everyone in the organization, and the ones an administrator assigned them. An administrator sees every one. Who a Team Bot reaches (people, groups and assignments) is shown only to its owner and administrators. Ordered by name, then the Bot''s id. A missing cursor starts at the first page and nextCursor null ends the list.'
security:
- webSession: []
- appOAuth:
@@ -13085,8 +14011,8 @@ paths:
tags:
- Team Bots
operationId: publishTeamBot
- summary: Publish a Bot to the team
- description: Publish one of the caller's own Bots to the whole team, or to named people and directory groups, or change who it is published to. Each person's conversations with it are private to them; its owner can't read them. Needs the caller's Team Bots switch, and a Bot with a real name and a description, which is how teammates tell it apart. Every person named must have signed in here. Publishing can widen who reaches the shared app accounts the Bot uses, and the answer says which an administrator still has to approve.
+ summary: Publish a Bot to everyone in the organization, or to some of them
+ description: Publish one of the caller's own Bots to everyone in the organization, or to named people, teams and directory groups, or change who it is published to. Each person's conversations with it are private to them; its owner can't read them. Needs the caller's Team Bots switch, and a Bot with a real name and a description, which is how the people it is published to tell it apart. Every person named must have signed in here. Publishing can widen who reaches the shared app accounts the Bot uses, and the answer says which an administrator still has to approve.
security:
- webSession: []
- appOAuth:
@@ -13102,7 +14028,7 @@ paths:
$ref: '#/components/schemas/TeamBotPublication'
examples:
team:
- summary: To the whole team.
+ summary: To everyone in the organization.
value:
audience: team
people:
@@ -13145,7 +14071,7 @@ paths:
- Team Bots
operationId: unpublishTeamBot
summary: Unpublish a Team Bot
- description: 'Stop publishing a Bot: teammates can''t use it until it is published again, and its assignments wait, doing nothing. Its owner or an administrator may unpublish it. Unpublishing a Bot that is not published changes nothing.'
+ description: 'Stop publishing a Bot: the people it was published to can''t use it until it is published again, and its assignments wait, doing nothing. Its owner or an administrator may unpublish it. Unpublishing a Bot that is not published changes nothing.'
security:
- webSession: []
- appOAuth:
@@ -13332,7 +14258,7 @@ paths:
- Computers
operationId: listComputers
summary: List the organization's computers
- description: 'Return one page of the computers Bots run on: each person''s, and each isolated Bot''s. Where every person''s Bots share one computer, each entry is one person''s seat on one Bot there. Ordered by whose computer it is, then by Bot. Only an administrator may read them. A missing cursor starts at the first page and nextCursor null ends the list.'
+ description: 'Return one page of the computers the organization''s Bots run on: each person''s, and each isolated Bot''s. Where every person''s Bots share one computer, each entry is one person''s seat on one Bot there. A computer another organization''s Bots run on is never listed. Ordered by whose computer it is, then by Bot. Only an administrator of the organization may read them. A missing cursor starts at the first page and nextCursor null ends the list.'
security:
- webSession: []
- appOAuth:
@@ -13376,7 +14302,7 @@ paths:
- Computers
operationId: stopComputer
summary: Stop a computer
- description: Stop one computer from the list now, and record it on the audit trail. Its files and sign-ins stay, and it starts again when a Bot next needs it. The computer is named by whose it is, person: or bot:; botId names one Bot's seat on a shared computer. Only an administrator may do this.
+ description: Stop one computer from the list now, and record it on the audit trail. Its files and sign-ins stay, and it starts again when a Bot next needs it. The computer is named by whose it is, person: or bot:; botId names one Bot's seat on a shared computer. A computer that is not one of the organization's is not found. Only an administrator of the organization may do this.
security:
- webSession: []
- appOAuth:
@@ -13414,7 +14340,7 @@ paths:
'403':
$ref: '#/components/responses/AdminOnly'
'404':
- $ref: '#/components/responses/OrganizationNotFound'
+ $ref: '#/components/responses/OrganizationComputerNotFound'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'500':
@@ -13431,7 +14357,7 @@ paths:
- Computers
operationId: resetComputer
summary: Reset a computer
- description: Delete one computer's browser profile, and every sign-in with it, and record it on the audit trail. The computer is named by whose it is, person: or bot:; botId names one Bot's seat on a shared computer. Only an administrator may do this.
+ description: Delete one computer's browser profile, and every sign-in with it, and record it on the audit trail. The computer is named by whose it is, person: or bot:; botId names one Bot's seat on a shared computer. A computer that is not one of the organization's is not found. Only an administrator of the organization may do this.
security:
- webSession: []
- appOAuth:
@@ -13469,7 +14395,7 @@ paths:
'403':
$ref: '#/components/responses/AdminOnly'
'404':
- $ref: '#/components/responses/OrganizationNotFound'
+ $ref: '#/components/responses/OrganizationComputerNotFound'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'500':
@@ -13486,7 +14412,7 @@ paths:
- Computers
operationId: updateComputer
summary: Update a computer
- description: Move one computer onto the image this OpenBot now runs, and record it on the audit trail. Files and sign-ins stay; a running computer restarts. The computer is named by whose it is, person: or bot:. Only an administrator may do this.
+ description: Move one computer onto the image this OpenBot now runs, and record it on the audit trail. Files and sign-ins stay; a running computer restarts. The computer is named by whose it is, person: or bot:. A computer that is not one of the organization's is not found. Only an administrator of the organization may do this.
security:
- webSession: []
- appOAuth:
@@ -13524,7 +14450,7 @@ paths:
'403':
$ref: '#/components/responses/AdminOnly'
'404':
- $ref: '#/components/responses/OrganizationNotFound'
+ $ref: '#/components/responses/OrganizationComputerNotFound'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'500':
@@ -15646,7 +16572,7 @@ paths:
- Sign-in requests
operationId: getSignInRequest
summary: Read a sign-in request
- description: 'Return one sign-in request as its private form shows it: where it has got to, the last thing that happened, and the usernames of the person''s saved logins for that site while the password manager is on. Never a credential. Only the person it was opened for may read it; anybody else''s is not found.'
+ description: 'Return one sign-in request as its private form shows it: where it has got to, the last thing that happened, and the usernames of the person''s saved logins for that site while the password manager is on. Never a credential. Only the person it was opened for may read it; anybody else''s is not found. A request belongs to the organization the Bot asked in, and is not found in any other, so the link a Bot hands the person (/sign-in/{signInRequestId}) opens only while they are working in that organization.'
security:
- webSession: []
- appOAuth:
@@ -16299,7 +17225,7 @@ paths:
- Recorder
operationId: deleteCurrentRecorderConnection
summary: Disconnect this browser's Recorder
- description: 'End the connection the request is signed with: the Recorder''s own Disconnect. Signed with the Recorder''s connection token and nothing else.'
+ description: 'End the connection the request is signed with: the Recorder''s own Disconnect. Signed with the Recorder''s connection token and nothing else. organizationId is `default` or the connection''s own organization, and either way the call acts in the connection''s organization.'
security:
- recorderConnection: []
parameters:
@@ -16331,7 +17257,7 @@ paths:
- Recorder
operationId: getRecorderIdentity
summary: Read who a Recorder is connected as
- description: Return the person this Recorder's connection acts as, and the connection's id. Signed with the Recorder's connection token and nothing else. A connection that has ended is refused as signed out, with why.
+ description: Return the person this Recorder's connection acts as, and the connection's id. Signed with the Recorder's connection token and nothing else. organizationId is `default` or the connection's own organization, and either way the answer is for the connection's organization. A connection that has ended is refused as signed out, with why.
x-openbot-singleton: true
security:
- recorderConnection: []
@@ -16368,7 +17294,7 @@ paths:
- Recorder
operationId: getRecorderLearning
summary: Read where a Recorder's recordings are learned from
- description: Return whether the recordings this Recorder's person makes land in their own Learning space, which is made on first need. Signed with the Recorder's connection token and nothing else.
+ description: Return whether the recordings this Recorder's person makes land in their own Learning space, which is made on first need. Signed with the Recorder's connection token and nothing else. organizationId is `default` or the connection's own organization, and either way the answer is for the connection's organization.
x-openbot-singleton: true
security:
- recorderConnection: []
@@ -16405,7 +17331,7 @@ paths:
- Recorder
operationId: reportRecorderActivity
summary: Say what a Recorder is doing now
- description: 'Report what this browser''s Recorder is doing, which it says whenever its recording phase changes and every 30 seconds while a recording runs, so OpenBot can show a recording wherever the person made it. Kept against the connection in place of the last report, and never audited: it is a heartbeat. Signed with the Recorder''s connection token and nothing else.'
+ description: 'Report what this browser''s Recorder is doing, which it says whenever its recording phase changes and every 30 seconds while a recording runs, so OpenBot can show a recording wherever the person made it. Kept against the connection in place of the last report, and never audited: it is a heartbeat. Signed with the Recorder''s connection token and nothing else. organizationId is `default` or the connection''s own organization, and either way the report is kept in the connection''s organization.'
security:
- recorderConnection: []
parameters:
@@ -18029,7 +18955,7 @@ paths:
- Memory
operationId: listMemories
summary: List a person's memories
- description: 'Return one page of what a person''s Bots remember about them, most recently changed first: the ones they wrote, the ones their Bots formed and are waiting for their review, the ones read in from their sources, and the ones the backend holds for them that OpenBot formed no record of, after OpenBot''s own. Paused memories are included; forgotten ones are not. Only the person themselves may list them: an administrator can''t either. A missing cursor starts at the first page and nextCursor null ends the list.'
+ description: 'Return one page of what a person''s Bots remember about them in this organization, and in no other they belong to, most recently changed first: the ones they wrote, the ones their Bots formed and are waiting for their review, the ones read in from their sources, and the ones the backend holds for them that OpenBot formed no record of, after OpenBot''s own. Paused memories are included; forgotten ones are not. Only the person themselves may list them: an administrator can''t either. A missing cursor starts at the first page and nextCursor null ends the list.'
security:
- webSession: []
- appOAuth:
@@ -18484,7 +19410,22 @@ components:
description: The web app's server-side session, so no token ever reaches the browser. Served over HTTPS the cookie is __Secure-better-auth.session_token. A single-user install signs its one person in without a cookie.
appOAuth:
type: oauth2
- description: Desktop and mobile. OAuth 2.1 authorization code with PKCE (RFC 7636, S256 only); the access token is sent as a bearer token.
+ description: |-
+ Desktop and mobile. OAuth 2.1 authorization code with PKCE (RFC 7636, S256 only); the access token is sent as a bearer token.
+
+ Clients. Three public clients are registered: `openbot-desktop-oauth`, `openbot-mobile` and `openbot-cli`. A public client has no secret and must use PKCE with S256. Dynamic client registration is off, so an app uses one of these ids.
+
+ Redirect addresses. A client on the person's own computer listens on a loopback address and any port: `http://127.0.0.1:/callback` or `http://[::1]:/callback`. `localhost` is not accepted.
+
+ Endpoints. The authorization server's metadata (RFC 8414) is at `/.well-known/oauth-authorization-server/api/auth`. The person is sent to `/api/auth/oauth2/authorize`. The code is exchanged, and a token refreshed, at `/api/auth/oauth2/token`, with a form-encoded body (`application/x-www-form-urlencoded`) that carries `client_id` and no secret: the token and revocation endpoints take no client authentication (`none` in the metadata's `token_endpoint_auth_methods_supported`). A wrong `code_verifier` is answered 400 `invalid_grant`, and the code cannot be used again. A token is revoked (RFC 7009) at `/api/auth/oauth2/revoke`; revoking a token the server does not know, or one already revoked, answers 200.
+
+ Tokens. An access token starts `oba_` and lasts one hour. A refresh token starts `obr_`, is issued only when the `offline_access` scope is asked for, and rotates on every use: each refresh answers a new refresh token and ends the one it was given. Access tokens work on /api/v2, and on four addresses outside it that an app's screens need, each with the scope given: `GET /api/me`, who is signed in (people:read); the chat runtime at `/api/copilotkit` and everything under it (conversations:write); a file's download at `GET /api/attachments/{attachmentId}`, the address a sent message keeps (conversations:read); and the relayed realtime socket at `/api/intelligence/client/websocket` (conversations:read). They work nowhere else.
+
+ Organization. An access token carries no memory of which organization the person is working in. An address under `/api/v2/organizations/{organizationId}` names it. Where an address names none, such as the list of the person's own organizations, an app sends the header `OpenBot-Organization` with the organization's id. It is checked against the person's membership on every request, and an organization they are not in answers not found. With no header, the app works in the person's own organization.
+
+ Consent. The person is asked once for each app, and not again for scopes they already allowed it.
+
+ An install for one person on one computer has no sign-in, so it has no OAuth: there is nobody to authorize an app as.
flows:
authorizationCode:
authorizationUrl: /api/auth/oauth2/authorize
@@ -18523,7 +19464,7 @@ components:
model-catalogue:read: Read the models Bots can run on.
model-choices:read: Read the model the signed-in person chose for each of their conversations.
model-choices:write: Choose the model the signed-in person's conversations answer on.
- apps:read: Read the apps this OpenBot has added, the directory of apps it can add, and how apps are set up here.
+ apps:read: Read the apps the organization has added, the directory of apps it can add, and how apps are set up here.
apps:write: Add, change, refresh and remove apps, when the signed-in person may.
connections:read: Read the signed-in person's connections to apps, and each app's shared account.
connections:write: Connect and disconnect the signed-in person's apps, and an app's shared account when the signed-in person is an administrator.
@@ -18574,7 +19515,7 @@ components:
type: http
scheme: bearer
bearerFormat: OpenBot API key
- description: Automation. An API key acts as the person who created it, inside one organization.
+ description: 'Automation. An API key acts as the person who created it, in every organization they are a member of, like a personal access token: the address of each request names the organization, and one the person is not in answers not found. A key starts `obk_` and is sent as `Authorization: Bearer ` or in an `x-api-key` header, on /api/v2 and on the relayed realtime socket at `/api/intelligence/client/websocket`, where a join token the key made is spent (createConversationJoinToken). A person makes one in the web app, signed in, under Settings, then API keys (createApiKey).'
recorderConnection:
type: http
scheme: bearer
@@ -18585,7 +19526,7 @@ components:
name: organizationId
in: path
required: true
- description: The organization, by its id or its slug. Every install has one addressed as `default`.
+ description: The organization, by its id or its slug. One the caller is not a member of answers as one that does not exist, `default` included.
schema:
type: string
minLength: 1
@@ -18652,12 +19593,12 @@ components:
name: networkPolicyId
in: path
required: true
- description: organization, or group: for a directory group's.
+ description: organization, team: for a team's, or group: for a directory group's.
schema:
type: string
minLength: 1
maxLength: 206
- pattern: ^(organization|group:[^\x00]*\S[^\x00]*)$
+ pattern: ^(organization|team:[^\x00]*\S[^\x00]*|group:[^\x00]*\S[^\x00]*)$
BotId:
name: botId
in: path
@@ -18709,7 +19650,7 @@ components:
AuditEventTypes:
name: eventType
in: query
- description: Events of any of these types, separated by commas, such as computer.action_refused,mcp.call_rejected.
+ description: Events of any of these types, separated by commas, such as computer.action_refused,mcp.call_rejected or organization.member_invited,organization.member_removed.
schema:
$ref: '#/components/schemas/AuditFilterText'
AuditExcludedEventTypes:
@@ -19018,6 +19959,38 @@ components:
minLength: 1
maxLength: 200
pattern: \S
+ InvitationId:
+ name: invitationId
+ in: path
+ required: true
+ description: The invitation's id. Opaque.
+ schema:
+ type: string
+ minLength: 1
+ maxLength: 128
+ pattern: ^[A-Za-z0-9_-]+$
+ TeamId:
+ name: teamId
+ in: path
+ required: true
+ description: The team's id. Opaque.
+ schema:
+ type: string
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
+ example: Tm4Qx8LpV2nWc7RbY1sKd0Ze
+ TeamMemberId:
+ name: memberId
+ in: path
+ required: true
+ description: The person's id, or me for the caller.
+ schema:
+ type: string
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
+ example: 2fn8w1c6y4tq7h0mbe3s
ApprovalId:
name: approvalId
in: path
@@ -19113,7 +20086,7 @@ components:
name: group
in: path
required: true
- description: A directory group, by the name the identity provider gives it, or * for everybody.
+ description: 'A directory group, by the name the identity provider gives it, or * for everybody. A team is written team: followed by the team''s id, as in team:Tm4Qx8LpV2nWc7RbY1sKd0Ze.'
schema:
type: string
minLength: 1
@@ -19326,6 +20299,12 @@ components:
systemOwned:
type: boolean
description: Whether it comes with OpenBot rather than belonging to a person.
+ packageBotId:
+ type:
+ - string
+ - 'null'
+ readOnly: true
+ description: 'Which of the Bots an OpenBot starts with this one is, so a client recognises it in whichever organization it is in. It is the id that Bot has in the install package: the same as id in the organization `default`, and the package''s id on another organization''s copy, whose own id is generated. Null for a Bot somebody made. Never accepted when a Bot is created or changed.'
endpoint:
type:
- string
@@ -19352,6 +20331,9 @@ components:
mine:
type: boolean
description: Whether the caller created it. Separate from canManage, which is also true for an administrator on everybody's Bots.
+ withheld:
+ type: boolean
+ description: 'Whether it is somebody else''s private Bot, listed for an admin''s screens (listBots with scope=organization) and nothing more. Such a Bot carries its id, name, avatar and the caller''s own state with it only: title and roleDescription are empty, endpoint is null, instructions and framework are absent, hasAuth, hasCallbackToken, isolated, builtIn, runsOnOpenBotModel, keyFromOpenBot and canManage are false. Absent or false on every other Bot.'
assignedToMe:
type: boolean
description: Whether an administrator assigned this Bot to the caller.
@@ -20603,7 +21585,7 @@ components:
readOnly: true
ssoRequired:
type: boolean
- description: Whether people must sign in through the organization's identity provider. The administrators the deployment's configuration names keep social sign-in as their way in.
+ description: Whether people must sign in through the company's identity provider. It applies to signing in to the whole OpenBot, so it is set only in the organization `default`. The administrators the deployment's configuration names keep social sign-in as their way in.
actionRecording:
type: boolean
description: Whether what Bots do on their computers is recorded, to read in computer actions.
@@ -20688,7 +21670,7 @@ components:
description: The model OpenBot's own Bots run on, when one is set.
directoryGroups:
type: array
- description: The directory groups people belong to, by name.
+ description: The directory groups the organization's members belong to, by name.
items:
type: string
apps:
@@ -20840,7 +21822,12 @@ components:
type: boolean
groups:
type: object
- description: What each directory group is set to, by the group's name. A group absent sets nothing. Team scopes will be added when teams arrive.
+ description: What each directory group is set to, by the group's name. A group absent sets nothing.
+ additionalProperties:
+ type: boolean
+ teams:
+ type: object
+ description: What each team is set to, by the team's id. A team absent sets nothing. A team's switch can only turn a permission on for the people in it, and in the teams beneath it.
additionalProperties:
type: boolean
CapabilityPage:
@@ -20887,7 +21874,18 @@ components:
type: object
minProperties: 1
maxProperties: 100
- description: By directory group name, 1 to 200 characters. Team scopes will be added when teams arrive.
+ description: By directory group name, 1 to 200 characters.
+ propertyNames:
+ minLength: 1
+ maxLength: 200
+ pattern: ^[^\x00]*\S[^\x00]*$
+ additionalProperties:
+ $ref: '#/components/schemas/SwitchValue'
+ teams:
+ type: object
+ minProperties: 1
+ maxProperties: 100
+ description: By team id. A team that is not one of this organization's is not found.
propertyNames:
minLength: 1
maxLength: 200
@@ -20908,12 +21906,13 @@ components:
- organization
- role
- group
- description: 'Whose switch: the organization''s, a member role''s, or a directory group''s. Team scopes will be added when teams arrive.'
+ - team
+ description: 'Whose switch: the organization''s, a member role''s, a team''s, or a directory group''s.'
scopeId:
type: string
maxLength: 200
pattern: ^[^\x00]*$
- description: Empty for the organization; admin or member for a role; a directory group's name for a group. Team scopes will be added when teams arrive.
+ description: Empty for the organization; admin or member for a role; a team's id for a team; a directory group's name for a group.
capability:
$ref: '#/components/schemas/CapabilityId'
allowed:
@@ -20961,12 +21960,13 @@ components:
- organization
- role
- group
- description: 'Whose switch: the organization''s, a member role''s, or a directory group''s. Team scopes will be added when teams arrive.'
+ - team
+ description: 'Whose switch: the organization''s, a member role''s, a team''s, or a directory group''s.'
scopeId:
type: string
maxLength: 200
pattern: ^[^\x00]*$
- description: Empty for the organization; admin or member for a role; a directory group's name for a group. Team scopes will be added when teams arrive.
+ description: Empty for the organization; admin or member for a role; a team's id for a team; a directory group's name for a group.
capability:
type: string
maxLength: 100
@@ -21065,10 +22065,11 @@ components:
- organization
- role
- group
- description: 'Whose switch: the organization''s, a member role''s, or a directory group''s. Team scopes will be added when teams arrive.'
+ - team
+ description: 'Whose switch: the organization''s, a member role''s, a team''s, or a directory group''s.'
scopeId:
type: string
- description: Empty for the organization; admin or member for a role; a directory group's name for a group.
+ description: Empty for the organization; admin or member for a role; a team's id for a team; a directory group's name for a group.
capability:
type: string
allowed:
@@ -21089,9 +22090,10 @@ components:
- organization
- role
- group
+ - team
scopeId:
type: string
- description: The role or group that decided it. Empty otherwise.
+ description: The role, the group's name or the team's id that decided it. Empty otherwise.
CapabilityPreview:
type: object
required:
@@ -21277,16 +22279,17 @@ components:
properties:
id:
type: string
- description: organization, or group: for a directory group. Team scopes will be added when teams arrive.
+ description: organization, team: for a team, or group: for a directory group.
scopeKind:
type: string
enum:
- organization
- group
- description: 'Whose policy: the organization''s, or a directory group''s. Team scopes will be added when teams arrive.'
+ - team
+ description: 'Whose policy: the organization''s, a team''s, or a directory group''s.'
scopeId:
type: string
- description: The directory group's name. Empty for the organization.
+ description: The team's id, or the directory group's name. Empty for the organization.
mode:
$ref: '#/components/schemas/NetworkMode'
rules:
@@ -21353,12 +22356,13 @@ components:
enum:
- organization
- group
- description: 'Whose policy: the organization''s, or a directory group''s. Team scopes will be added when teams arrive.'
+ - team
+ description: 'Whose policy: the organization''s, a team''s, or a directory group''s.'
scopeId:
type: string
maxLength: 200
pattern: ^[^\x00]*$
- description: The directory group's name. Empty for the organization.
+ description: The team's id, or the directory group's name. Empty for the organization.
mode:
$ref: '#/components/schemas/NetworkMode'
rules:
@@ -21771,11 +22775,11 @@ components:
clientUrl:
type: string
minLength: 1
- description: The socket's address, without the /websocket it ends in or its query. A ws or wss address, or a path on this server.
+ description: The socket's address, without the /websocket it ends in or its query. A ws or wss address, or a path on this server, which is resolved against the address the API was called at. Where it is on this server, the socket is opened with the credential that made the token (see createConversationJoinToken).
topic:
type: string
pattern: ^thread:.+$
- description: The topic to join on the socket, thread:{threadId}.
+ description: 'The topic to join on the socket, as the realtime gateway knows the thread. Use it as given: outside the organization default it does not name threadId, so a topic made from threadId joins nothing.'
CredentialKind:
type: string
description: 'What a credential is for. model: a key OpenBot''s Bots call a model with. connector: an app''s key. mcp: a token for an app''s server. agent: a key for a company''s own agent. mcp_oauth_client: the organization''s registration with an app. mcp_user_token: one person''s sign-in to an app, kept when they connected it.'
@@ -21788,7 +22792,7 @@ components:
- mcp_user_token
Credential:
type: object
- description: 'A credential in the vault as the API shows it: what it is for and whether it is live. Never its secret, which only ever goes in.'
+ description: 'A credential in the organization''s vault as the API shows it: what it is for and whether it is live. Never its secret, which only ever goes in.'
required:
- id
- kind
@@ -22014,7 +23018,7 @@ components:
SharedAccountApproval:
type: object
additionalProperties: false
- description: 'Who may have a Bot use an app''s one shared account, approved by an administrator: only the Bot''s owner, named people and directory groups, or everybody; and whether the Bot may act on what people outside the organization send it.'
+ description: 'Who may have a Bot use an app''s one shared account, approved by an administrator: only the Bot''s owner, named people, teams and directory groups, or everyone in the organization (team); and whether the Bot may act on what people outside the organization send it. A member of kind team names one of the organization''s teams by id; a team of another organization is not found.'
required:
- audience
- outsideInput
@@ -22043,6 +23047,7 @@ components:
enum:
- user
- group
+ - team
value:
type: string
minLength: 1
@@ -22563,7 +23568,7 @@ components:
properties:
id:
type: string
- description: The caller's own id for the message, so a retry is the same message.
+ description: The caller's own id for the message, any string, so a retry in the same conversation is the same message. The conversation's messages list it under this id.
minLength: 1
maxLength: 160
text:
@@ -22815,6 +23820,9 @@ components:
threadId:
type: string
description: The new thread's id.
+ liveThreadId:
+ type: string
+ description: The id that live updates about this thread carry. Compare an incoming update with this one, and use threadId everywhere else. It is threadId itself in the organization default. Left out by a server that names threads one way only, where it is threadId.
ConversationThreadStatus:
type: object
required:
@@ -22826,6 +23834,9 @@ components:
known:
type: boolean
description: Whether the thread still holds the caller's conversation.
+ liveThreadId:
+ type: string
+ description: The id that live updates about this thread carry. Compare an incoming update with this one, and use threadId everywhere else. It is threadId itself in the organization default. Left out by a server that names threads one way only, where it is threadId.
TaskStatus:
type: string
enum:
@@ -23040,7 +24051,7 @@ components:
enum:
- personal
- shared
- description: Each person's own account, or one account OpenBot holds for everybody.
+ description: Each person's own account, or one account OpenBot holds for everybody in the organization.
AppOwnerGrants:
type: string
enum:
@@ -23102,7 +24113,7 @@ components:
type: string
App:
type: object
- description: 'An app this OpenBot has added for its Bots, with the actions it offers. No secret is ever part of an app: hasCredential says whether a key or client is kept for it.'
+ description: 'An app the organization has added for its Bots, with the actions it offers. No secret is ever part of an app: hasCredential says whether a key or client is kept for it.'
required:
- id
- title
@@ -23187,7 +24198,7 @@ components:
oneOf:
- $ref: '#/components/schemas/AppAccountMode'
- type: 'null'
- description: 'Whose account an app from the directory acts in: each person''s own, or one account OpenBot holds for everybody. Null for an app with no account at all, and for any other app.'
+ description: 'Whose account an app from the directory acts in: each person''s own, or one account OpenBot holds for everybody in the organization. Null for an app with no account at all, and for any other app.'
sharedAccountConnected:
type: boolean
description: Whether a shared app's one account is connected. False for any other app.
@@ -23420,7 +24431,7 @@ components:
enum:
- person
- deployment
- description: 'Whose accounts they are: people''s own (person), or the one OpenBot holds for everybody (deployment).'
+ description: 'Whose accounts they are: people''s own (person), or the one OpenBot holds for everybody in the organization (deployment).'
count:
type: integer
minimum: 0
@@ -24864,6 +25875,32 @@ components:
description: The actions given to the Bot, written /.
items:
type: string
+ AppTeamGrants:
+ type: object
+ description: The teams the app is granted to.
+ required:
+ - teams
+ properties:
+ teams:
+ type: array
+ description: Each team's id, in order.
+ items:
+ type: string
+ AppTeamGrantsInput:
+ type: object
+ additionalProperties: false
+ required:
+ - teams
+ properties:
+ teams:
+ type: array
+ maxItems: 100
+ description: The id of each team of this organization to grant it to.
+ items:
+ type: string
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
GiveableApp:
type: object
description: An app a person could give Bots they own.
@@ -25135,7 +26172,7 @@ components:
type: string
minLength: 1
pattern: \S
- description: The tool name a Bot draws it by. Trimmed.
+ description: The tool name a Bot draws it by. Trimmed. It can't start with @.
title:
type: string
minLength: 1
@@ -25328,6 +26365,7 @@ components:
- tools
- ownerId
- botIds
+ - usableOnYourBots
properties:
slug:
type: string
@@ -25357,6 +26395,9 @@ components:
description: The Bots that offer it, by id.
items:
type: string
+ usableOnYourBots:
+ type: boolean
+ description: 'Whether the caller may put it on a Bot they own: it is their own, or it is granted to a team they are in. A Bot''s Skills page offers these.'
SkillPage:
type: object
required:
@@ -25408,6 +26449,32 @@ components:
type: boolean
default: false
description: 'Make a new skill the organization''s. Only an admin may. It applies when the skill is made: rewriting one keeps whose it is.'
+ SkillTeamGrants:
+ type: object
+ description: The teams the skill is granted to.
+ required:
+ - teams
+ properties:
+ teams:
+ type: array
+ description: Each team's id, in order.
+ items:
+ type: string
+ SkillTeamGrantsInput:
+ type: object
+ additionalProperties: false
+ required:
+ - teams
+ properties:
+ teams:
+ type: array
+ maxItems: 100
+ description: The id of each team of this organization to grant it to.
+ items:
+ type: string
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
DevicePlatform:
type: string
enum:
@@ -27346,7 +28413,11 @@ components:
- name
- role
- active
+ - personal
properties:
+ personal:
+ type: boolean
+ description: 'Whether this is the caller''s own organization: the one OpenBot made for them when they first signed in.'
id:
type: string
description: The organization's id. Opaque.
@@ -27360,7 +28431,7 @@ components:
$ref: '#/components/schemas/PersonRole'
active:
type: boolean
- description: Whether the caller's session is working in this one. Always false for a request with no session.
+ description: 'Whether the caller is working in this one: the organization their session works in, or for an app''s token the one its OpenBot-Organization header names, else the caller''s own. Always false for a request made with an API key.'
OrganizationPage:
type: object
required:
@@ -27375,7 +28446,7 @@ components:
$ref: '#/components/schemas/Organization'
canCreate:
type: boolean
- description: 'Whether the caller may create an organization: the server''s verdict, true for the deployment''s admins and for anybody signed in when the deployment lets them. The same on every page.'
+ description: 'Whether the caller may create another organization: the server''s verdict, true for anybody signed in where OpenBot keeps more than one organization. The same on every page.'
nextCursor:
type:
- string
@@ -27418,7 +28489,17 @@ components:
- image
- role
- joinedAt
+ - removable
+ - assignableRoles
properties:
+ removable:
+ type: boolean
+ description: 'Whether this membership can end: an admin can remove them and they can leave. The server''s verdict. False for the organization''s last owner, who stays in it, for the owner of their own organization, and for somebody this OpenBot''s settings keep as an admin of the organization.'
+ assignableRoles:
+ type: array
+ description: The roles the caller may give this member, their current one left out. The server's verdict. Empty when the caller may not change this member's role.
+ items:
+ $ref: '#/components/schemas/PersonRole'
id:
type: string
description: The person's id.
@@ -27459,7 +28540,104 @@ components:
maxLength: 4096
pattern: ^[A-Za-z0-9_-]+$
description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts.
- AddOrganizationMemberRequest:
+ UpdateOrganizationRequest:
+ type: object
+ additionalProperties: false
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ minLength: 1
+ maxLength: 100
+ pattern: ^[^\x00]*\S[^\x00]*$
+ description: What people call it.
+ UpdateOrganizationMemberRequest:
+ type: object
+ additionalProperties: false
+ required:
+ - role
+ properties:
+ role:
+ $ref: '#/components/schemas/PersonRole'
+ OrganizationMemberResponse:
+ type: object
+ required:
+ - member
+ properties:
+ member:
+ $ref: '#/components/schemas/OrganizationMember'
+ InvitationSender:
+ type: object
+ description: Who sent an invitation.
+ required:
+ - name
+ - email
+ properties:
+ name:
+ type:
+ - string
+ - 'null'
+ description: What OpenBot calls them. Null until they choose.
+ email:
+ type: string
+ description: Their address.
+ OrganizationInvitation:
+ type: object
+ description: An invitation an organization sent, as its admins see it. status is the server's verdict.
+ required:
+ - id
+ - email
+ - role
+ - status
+ - invitedBy
+ - createdAt
+ - expiresAt
+ properties:
+ id:
+ type: string
+ description: The invitation's id. Opaque.
+ email:
+ type: string
+ description: The address it was sent to.
+ role:
+ $ref: '#/components/schemas/AssignableRole'
+ status:
+ type: string
+ enum:
+ - pending
+ - expired
+ - declined
+ description: pending while it waits for an answer, expired once its seven days ran out, declined when the person turned it down.
+ invitedBy:
+ $ref: '#/components/schemas/InvitationSender'
+ createdAt:
+ type: string
+ format: date-time
+ description: When it was sent.
+ expiresAt:
+ type: string
+ format: date-time
+ description: When it stops being accepted.
+ OrganizationInvitationPage:
+ type: object
+ required:
+ - invitations
+ - nextCursor
+ properties:
+ invitations:
+ type: array
+ description: The newest first.
+ items:
+ $ref: '#/components/schemas/OrganizationInvitation'
+ nextCursor:
+ type:
+ - string
+ - 'null'
+ maxLength: 4096
+ pattern: ^[A-Za-z0-9_-]+$
+ description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts.
+ CreateOrganizationInvitationRequest:
type: object
additionalProperties: false
required:
@@ -27471,16 +28649,317 @@ components:
minLength: 3
maxLength: 320
pattern: ^[^\s\x00]+@[^\s\x00]+$
- description: The address of somebody who already has an account here.
+ description: The address of the person to invite.
role:
$ref: '#/components/schemas/AssignableRole'
- OrganizationMemberResponse:
+ OrganizationInvitationResponse:
+ type: object
+ required:
+ - invitation
+ - delivery
+ properties:
+ invitation:
+ $ref: '#/components/schemas/OrganizationInvitation'
+ delivery:
+ type: string
+ enum:
+ - emailed
+ - link
+ description: How the person hears of it. emailed when OpenBot sent them an email. link when it could not or is not set up to, so the inviter passes the invitation's link on themselves. Either way the person sees the invitation in OpenBot when they sign in.
+ Invitation:
+ type: object
+ description: An invitation as the person it was sent to sees it. status is the server's verdict.
+ required:
+ - id
+ - organization
+ - role
+ - status
+ - invitedBy
+ - createdAt
+ - expiresAt
+ properties:
+ id:
+ type: string
+ description: The invitation's id. Opaque.
+ organization:
+ type: object
+ description: The organization it is an invitation to.
+ required:
+ - id
+ - slug
+ - name
+ properties:
+ id:
+ type: string
+ description: The organization's id. Opaque.
+ slug:
+ type: string
+ description: Its short name.
+ name:
+ type: string
+ description: What people call it.
+ role:
+ $ref: '#/components/schemas/AssignableRole'
+ status:
+ type: string
+ enum:
+ - pending
+ - expired
+ - accepted
+ - declined
+ - canceled
+ description: pending while it can still be answered. expired once its seven days ran out, accepted or declined once the person answered, canceled when the organization took it back.
+ invitedBy:
+ $ref: '#/components/schemas/InvitationSender'
+ createdAt:
+ type: string
+ format: date-time
+ description: When it was sent.
+ expiresAt:
+ type: string
+ format: date-time
+ description: When it stops being accepted.
+ InvitationPage:
+ type: object
+ required:
+ - invitations
+ - nextCursor
+ properties:
+ invitations:
+ type: array
+ description: The newest first.
+ items:
+ $ref: '#/components/schemas/Invitation'
+ nextCursor:
+ type:
+ - string
+ - 'null'
+ maxLength: 4096
+ pattern: ^[A-Za-z0-9_-]+$
+ description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts.
+ InvitationResponse:
+ type: object
+ required:
+ - invitation
+ properties:
+ invitation:
+ $ref: '#/components/schemas/Invitation'
+ TeamSource:
+ type: string
+ description: 'Where a team comes from. openbot is a team made here. directory is a group of the company''s directory, kept in step with it: its name and its people are the directory''s and can''t be changed here.'
+ enum:
+ - openbot
+ - directory
+ TeamRole:
+ type: string
+ description: A person's role in a team. A maintainer can rename the team and add and remove its people; a member cannot.
+ enum:
+ - maintainer
+ - member
+ Team:
+ type: object
+ description: One team of an organization, as one of the organization's members sees it. role and canManage are the server's verdicts about the caller.
+ required:
+ - id
+ - name
+ - description
+ - parentTeamId
+ - source
+ - memberCount
+ - role
+ - canManage
+ - canMove
+ - canDelete
+ - createdAt
+ properties:
+ id:
+ type: string
+ description: The team's id. Opaque.
+ name:
+ type: string
+ description: What people call it. Unique in its organization.
+ description:
+ type:
+ - string
+ - 'null'
+ description: What the team is for, when somebody has said.
+ parentTeamId:
+ type:
+ - string
+ - 'null'
+ description: The team this one sits under, whose grants its members also have. Null for a team under none.
+ source:
+ $ref: '#/components/schemas/TeamSource'
+ memberCount:
+ type: integer
+ minimum: 0
+ description: How many people are in the team itself.
+ role:
+ oneOf:
+ - $ref: '#/components/schemas/TeamRole'
+ - type: 'null'
+ description: The caller's role in the team. Null when they are not in it.
+ canManage:
+ type: boolean
+ description: 'Whether the caller may rename the team and add and remove its people: the server''s verdict.'
+ canMove:
+ type: boolean
+ description: 'Whether the caller may put the team under another team or take it out from under one: the server''s verdict, true for an owner or an admin of the organization.'
+ canDelete:
+ type: boolean
+ description: 'Whether the caller may delete the team: the server''s verdict, true for an owner or an admin of the organization, and never for a team that comes from the company''s directory.'
+ createdAt:
+ type: string
+ format: date-time
+ description: When the team was created.
+ TeamPage:
+ type: object
+ required:
+ - teams
+ - canCreate
+ - nextCursor
+ properties:
+ teams:
+ type: array
+ description: In the order they were created.
+ items:
+ $ref: '#/components/schemas/Team'
+ canCreate:
+ type: boolean
+ description: 'Whether the caller may create a team here: the server''s verdict. The same on every page.'
+ nextCursor:
+ type:
+ - string
+ - 'null'
+ maxLength: 4096
+ pattern: ^[A-Za-z0-9_-]+$
+ description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts.
+ CreateTeamRequest:
+ type: object
+ additionalProperties: false
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ minLength: 1
+ maxLength: 100
+ pattern: ^[^\x00]*\S[^\x00]*$
+ description: What people call it.
+ description:
+ type: string
+ maxLength: 500
+ pattern: ^[^\x00]*$
+ description: What the team is for.
+ parentTeamId:
+ type: string
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
+ description: A team of the same organization to put this one under.
+ TeamResponse:
+ type: object
+ required:
+ - team
+ properties:
+ team:
+ $ref: '#/components/schemas/Team'
+ UpdateTeamRequest:
+ type: object
+ additionalProperties: false
+ minProperties: 1
+ properties:
+ name:
+ type: string
+ minLength: 1
+ maxLength: 100
+ pattern: ^[^\x00]*\S[^\x00]*$
+ description: What people call it.
+ description:
+ type:
+ - string
+ - 'null'
+ maxLength: 500
+ pattern: ^[^\x00]*$
+ description: What the team is for. Null clears it.
+ parentTeamId:
+ type:
+ - string
+ - 'null'
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
+ description: A team of the same organization to put this one under. Null takes it out from under its parent.
+ TeamMember:
+ type: object
+ description: One person in a team.
+ required:
+ - id
+ - email
+ - name
+ - image
+ - role
+ - isCaller
+ - joinedAt
+ properties:
+ id:
+ type: string
+ description: The person's id.
+ email:
+ type: string
+ description: Their address.
+ name:
+ type:
+ - string
+ - 'null'
+ description: What OpenBot calls them. Null until they choose.
+ image:
+ type:
+ - string
+ - 'null'
+ description: Their picture's address, when they have one.
+ role:
+ $ref: '#/components/schemas/TeamRole'
+ isCaller:
+ type: boolean
+ description: Whether this person is the caller.
+ joinedAt:
+ type: string
+ format: date-time
+ description: When they joined the team.
+ TeamMemberPage:
+ type: object
+ required:
+ - members
+ - nextCursor
+ properties:
+ members:
+ type: array
+ description: In the order they joined the team.
+ items:
+ $ref: '#/components/schemas/TeamMember'
+ nextCursor:
+ type:
+ - string
+ - 'null'
+ maxLength: 4096
+ pattern: ^[A-Za-z0-9_-]+$
+ description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts.
+ PutTeamMemberRequest:
+ type: object
+ additionalProperties: false
+ required:
+ - role
+ properties:
+ role:
+ $ref: '#/components/schemas/TeamRole'
+ TeamMemberResponse:
type: object
required:
- member
properties:
member:
- $ref: '#/components/schemas/OrganizationMember'
+ $ref: '#/components/schemas/TeamMember'
ApprovalStatus:
type: string
description: Where an approval stands. pending waits for the person. approved and denied are decided, and consumed is started; the server then carries the conversation on. completed is finished.
@@ -29174,6 +30653,19 @@ components:
description: The directory groups, by name.
items:
type: string
+ teams:
+ type: array
+ description: The organization's teams. An action names one in group, as team:.
+ items:
+ type: object
+ required:
+ - id
+ - name
+ properties:
+ id:
+ type: string
+ name:
+ type: string
apps:
type: array
items:
@@ -29231,7 +30723,7 @@ components:
WhatIfAction:
type: object
additionalProperties: false
- description: 'One action a Bot might take. Who: a Bot, and either the person whose accounts it runs on or a directory group, for any member of it. What starts the run. Then either an app''s tool, or something on the Bot''s computer. A field that does not apply is empty.'
+ description: 'One action a Bot might take. Who: a Bot, and either the person whose accounts it runs on or a team or directory group, for any member of it. What starts the run. Then either an app''s tool, or something on the Bot''s computer. A field that does not apply is empty.'
required:
- bot
- person
@@ -29254,7 +30746,7 @@ components:
description: The person's id. Empty when a group is named.
group:
type: string
- description: A directory group's name. Empty when a person is named.
+ description: A directory group's name, or team: for one of the organization's teams. Empty when a person is named.
initiator:
$ref: '#/components/schemas/WhatIfInitiator'
surface:
@@ -29532,10 +31024,10 @@ components:
- owner
- people
- team
- description: 'Who may steer a Bot that uses a shared app''s account: only the Bot''s owner, the people and directory groups named, or everybody in the organization.'
+ description: 'Who may steer a Bot that uses a shared app''s account: only the Bot''s owner, the people, teams and directory groups named, or everyone in the organization (team).'
SharedUseMember:
type: object
- description: One person or directory group an audience names.
+ description: One person, team or directory group an audience names.
required:
- kind
- value
@@ -29545,9 +31037,10 @@ components:
enum:
- user
- group
+ - team
value:
type: string
- description: The person's id, or the directory group's name.
+ description: The person's id, the team's id, or the directory group's name.
SharedUseApproval:
type: object
description: 'An audience for a Bot''s use of a shared app''s account: who may steer the Bot there, and whether a run started by outside input (an email, a webhook) may use the account too.'
@@ -29563,7 +31056,7 @@ components:
description: Whether runs started by outside input are covered.
members:
type: array
- description: The people and groups named, when the audience is people. Empty otherwise.
+ description: The people, teams and groups named, when the audience is people. Empty otherwise.
items:
$ref: '#/components/schemas/SharedUseMember'
SharedUseRequest:
@@ -30249,10 +31742,10 @@ components:
enum:
- team
- people
- description: team is everybody in the organization; people is the people and groups named.
+ description: team is everyone in the organization; people is the people, teams and groups named.
TeamBot:
type: object
- description: A Bot published to the team, as the caller sees it. Who it reaches (people, groups and assignedGroups) is present only for its owner and administrators.
+ description: A published Bot, as the caller sees it. Who it reaches (people, teams, groups and assignedGroups) is present only for its owner and administrators.
required:
- botId
- name
@@ -30285,7 +31778,7 @@ components:
description: Whether an administrator put it in the caller's Bots list, where they can't hide it.
visibleToTeam:
type: boolean
- description: False while its name or description would leave teammates unable to tell it apart, so they can't see it.
+ description: False while its name or description would leave the people it is published to unable to tell it apart, so they can't see it.
people:
type: array
description: The people it is published to, by email.
@@ -30296,6 +31789,11 @@ components:
description: The directory groups it is published to.
items:
type: string
+ teams:
+ type: array
+ description: The teams it is published to, by each team's id.
+ items:
+ type: string
assignedGroups:
type: array
description: The directory groups an administrator assigned it to; * is everybody.
@@ -30347,6 +31845,15 @@ components:
items:
type: string
maxLength: 200
+ teams:
+ type: array
+ maxItems: 100
+ description: With people, the teams to publish to, by each team's id. Every one must be a team of this organization. The people in a team, and in the teams under it, can use the Bot, and nobody else in the organization can.
+ items:
+ type: string
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
PublishedTeamBot:
type: object
required:
@@ -30379,7 +31886,7 @@ components:
description: 'allow_once: this time. allow_always: always, for this Team Bot. allow_all_team_bots: always, for every Team Bot. skip: not now, taking back an earlier answer for this Team Bot.'
Computer:
type: object
- description: 'One computer as an administrator sees it: a person''s, or an isolated Bot''s. Where every person''s Bots share one computer, one person''s seat on one Bot there.'
+ description: 'One of the organization''s computers as its administrator sees it: a person''s, or an isolated Bot''s. Where every person''s Bots share one computer, one person''s seat on one Bot there.'
required:
- id
- computer
@@ -32354,6 +33861,11 @@ components:
oneOf:
- $ref: '#/components/schemas/LearningAutomatic'
- type: 'null'
+ organizationSpaceId:
+ description: 'The space OpenBot keeps for this organization alone, which its Bots learn into unless an administrator chooses another. Another space of the organization''s is named after it: this id, a hyphen, then a name of the administrator''s choosing. The id says nothing a person can read, so a screen names the space by the organization and never shows it. Null, or absent, where OpenBot keeps no space for the organization alone and its default is whichever space is assigned or chosen.'
+ oneOf:
+ - $ref: '#/components/schemas/LearningSpaceId'
+ - type: 'null'
UpdateLearningSettingsRequest:
type: object
additionalProperties: false
@@ -32738,7 +34250,7 @@ components:
- closed
- open
- choose
- description: 'Who else''s Bots use the skills learned in a person''s own space. closed: only their own Bots. open: every Bot. choose: every Bot, for the skills they open one by one.'
+ description: 'Who else''s Bots use the skills learned in a person''s own space. closed: only their own Bots. open: every Bot in the organization. choose: every Bot in the organization, for the skills they open one by one. Never a Bot in another organization.'
PersonalLearnedSkill:
type: object
required:
@@ -34096,12 +35608,23 @@ components:
requestId: req_example
traceId: trace_example
SettingsConflict:
- description: Single sign-on can't be required before an identity provider is registered, or the Idempotency-Key was used for a different request.
+ description: Single sign-on can't be required before an identity provider is registered, ssoRequired was sent in an organization other than `default`, or the Idempotency-Key was used for a different request.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
examples:
+ notTheFirstOrganization:
+ value:
+ type: https://open.bot/errors/conflict
+ title: The request conflicts with the current state.
+ status: 409
+ detail: Requiring SSO applies to signing in to this OpenBot as a whole, so it can't be set for one organization.
+ code: CONFLICT
+ category: conflict
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
noProvider:
value:
type: https://open.bot/errors/conflict
@@ -35419,6 +36942,35 @@ components:
retryable: false
requestId: req_example
traceId: trace_example
+ AppOrTeamNotFound:
+ description: OpenBot has no app by that id, a team named is not one of this organization's, or the organization does not exist.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/Problem'
+ examples:
+ app:
+ value:
+ type: https://open.bot/errors/app-not-found
+ title: App not found.
+ status: 404
+ detail: OpenBot has no app called asana.
+ code: APP_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ team:
+ value:
+ type: https://open.bot/errors/team-not-found
+ title: Team not found.
+ status: 404
+ detail: Couldn't find that team.
+ code: TEAM_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
TooManyPendingRequests:
description: The person already has as many requests waiting as they may.
content:
@@ -35485,12 +37037,23 @@ components:
requestId: req_example
traceId: trace_example
InvalidComponent:
- description: 'A field is missing or blank once trimmed, holds text that can''t be kept, or doesn''t fit this kind of component: a title or source for one that comes with OpenBot, a Playground name that isn''t custom_ and lower-case letters, numbers and underscores, or a data function this OpenBot doesn''t ship.'
+ description: 'A field is missing or blank once trimmed, holds text that can''t be kept, or doesn''t fit this kind of component: a title or source for one that comes with OpenBot, a Playground name that isn''t custom_ and lower-case letters, numbers and underscores, an announced name that starts with @, or a data function this OpenBot doesn''t ship.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
examples:
+ nameStartsWithAt:
+ value:
+ type: https://open.bot/errors/validation-error
+ title: Request validation failed.
+ status: 400
+ detail: Component at index 0 has a name that starts with @, which a component's name can't.
+ code: VALIDATION_ERROR
+ category: validation
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
announcement:
value:
type: https://open.bot/errors/validation-error
@@ -35608,7 +37171,7 @@ components:
requestId: req_example
traceId: trace_example
SkillNotFound:
- description: No skill has that slug, it is somebody else's and the caller isn't an admin, or the organization does not exist.
+ description: No skill has that slug, the caller isn't an admin and can't see it, or the organization does not exist.
content:
application/problem+json:
schema:
@@ -35683,6 +37246,35 @@ components:
retryable: false
requestId: req_example
traceId: trace_example
+ SkillOrTeamNotFound:
+ description: There is no skill by that slug, a team named is not one of this organization's, or the organization does not exist.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/Problem'
+ examples:
+ skill:
+ value:
+ type: https://open.bot/errors/skill-not-found
+ title: Skill not found.
+ status: 404
+ detail: There is no skill called standup.
+ code: SKILL_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ team:
+ value:
+ type: https://open.bot/errors/team-not-found
+ title: Team not found.
+ status: 404
+ detail: Couldn't find that team.
+ code: TEAM_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
TransportUnavailable:
description: 'This deployment hasn''t set up that way of reaching people: push notifications, the Slack and Teams pairing, or text messages. Or the organization does not exist.'
content:
@@ -35749,12 +37341,23 @@ components:
requestId: req_example
traceId: trace_example
InvalidDestination:
- description: The request doesn't match the API, the conversation isn't the person's or the Bot isn't in it, a phone's verification expired, was used already or its code was wrong, or the phone is connected to another person.
+ description: The request doesn't match the API, the conversation isn't the person's or the Bot isn't in it, a phone's verification expired, was used already or its code was wrong, the phone is connected to another person, or the Slack account, Teams account or phone is connected in another organization.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
examples:
+ connectedInAnotherOrganization:
+ value:
+ type: https://open.bot/errors/validation-error
+ title: Request validation failed.
+ status: 400
+ detail: That account is already connected to OpenBot in another organization. Disconnect it there, then connect it here.
+ code: VALIDATION_ERROR
+ category: validation
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
notTheirs:
value:
type: https://open.bot/errors/validation-error
@@ -36106,7 +37709,25 @@ components:
retryable: true
requestId: req_example
traceId: trace_example
- InvalidOrganizationMember:
+ OwnerStays:
+ description: 'The person stays in the organization: they own it, or this OpenBot''s settings keep them as an admin of it. The members list says who, as removable.'
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/Problem'
+ examples:
+ owner:
+ value:
+ type: https://open.bot/errors/conflict
+ title: The request conflicts with the current state.
+ status: 409
+ detail: They own this organization, so they stay a member of it.
+ code: CONFLICT
+ category: conflict
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ InvalidOrganizationInvitation:
description: The address or the role is missing or malformed, or the Idempotency-Key is.
content:
application/problem+json:
@@ -36124,8 +37745,48 @@ components:
retryable: false
requestId: req_example
traceId: trace_example
- OrganizationOrPersonNotFound:
- description: The organization does not exist or is not visible to the caller, or nobody here has that address.
+ OrganizationInvitationConflict:
+ description: They are already a member, or already have an invitation waiting. Or the Idempotency-Key was used for a different request.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/Problem'
+ examples:
+ already:
+ value:
+ type: https://open.bot/errors/conflict
+ title: The request conflicts with the current state.
+ status: 409
+ detail: They're already a member of this organization.
+ code: CONFLICT
+ category: conflict
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ invited:
+ value:
+ type: https://open.bot/errors/conflict
+ title: The request conflicts with the current state.
+ status: 409
+ detail: They already have an invitation waiting. Cancel it to send a new one.
+ code: CONFLICT
+ category: conflict
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ reused:
+ value:
+ type: https://open.bot/errors/idempotency-key-conflict
+ title: That Idempotency-Key was used for a different request.
+ status: 409
+ detail: That Idempotency-Key was used for a different request.
+ code: IDEMPOTENCY_KEY_CONFLICT
+ category: conflict
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ OrganizationOrInvitationNotFound:
+ description: The organization does not exist or is not visible to the caller, or it has no such invitation.
content:
application/problem+json:
schema:
@@ -36142,30 +37803,48 @@ components:
retryable: false
requestId: req_example
traceId: trace_example
- person:
+ invitation:
value:
- type: https://open.bot/errors/person-not-found
- title: Person not found.
+ type: https://open.bot/errors/invitation-not-found
+ title: Invitation not found.
status: 404
- detail: Nobody here has that address. They need to sign in to OpenBot once first.
- code: PERSON_NOT_FOUND
+ detail: Couldn't find that invitation.
+ code: INVITATION_NOT_FOUND
category: not_found
retryable: false
requestId: req_example
traceId: trace_example
- OrganizationMemberConflict:
- description: They are already a member. Or the Idempotency-Key was used for a different request.
+ InvitationNotFound:
+ description: There is no such invitation, or it was sent to another address.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
examples:
- already:
+ invitation:
+ value:
+ type: https://open.bot/errors/invitation-not-found
+ title: Invitation not found.
+ status: 404
+ detail: Couldn't find that invitation. Check that you're signed in with the address it was sent to.
+ code: INVITATION_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ InvitationNotWaiting:
+ description: The invitation expired, was canceled or was already answered. Or the Idempotency-Key was used for a different request.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/Problem'
+ examples:
+ expired:
value:
type: https://open.bot/errors/conflict
title: The request conflicts with the current state.
status: 409
- detail: They're already a member of this organization.
+ detail: This invitation has expired. Ask whoever invited you to send a new one.
code: CONFLICT
category: conflict
retryable: false
@@ -36182,6 +37861,169 @@ components:
retryable: false
requestId: req_example
traceId: trace_example
+ InvalidTeam:
+ description: The name, the description or the parent is missing or malformed, the parent is not a team that can hold this one, or the Idempotency-Key is malformed.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/Problem'
+ examples:
+ name:
+ value:
+ type: https://open.bot/errors/validation-error
+ title: Request validation failed.
+ status: 400
+ detail: A name of 1 to 100 characters is required.
+ code: VALIDATION_ERROR
+ category: validation
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ parent:
+ value:
+ type: https://open.bot/errors/validation-error
+ title: Request validation failed.
+ status: 400
+ detail: A team can't sit under itself or under a team beneath it.
+ code: VALIDATION_ERROR
+ category: validation
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ TeamConflict:
+ description: Another team of the organization has that name. Or the Idempotency-Key was used for a different request.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/Problem'
+ examples:
+ nameTaken:
+ value:
+ type: https://open.bot/errors/conflict
+ title: The request conflicts with the current state.
+ status: 409
+ detail: Another team here already has that name. Choose another.
+ code: CONFLICT
+ category: conflict
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ reused:
+ value:
+ type: https://open.bot/errors/idempotency-key-conflict
+ title: That Idempotency-Key was used for a different request.
+ status: 409
+ detail: That Idempotency-Key was used for a different request.
+ code: IDEMPOTENCY_KEY_CONFLICT
+ category: conflict
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ TeamNotFound:
+ description: The organization or the team does not exist or is not visible to the caller.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/Problem'
+ examples:
+ organization:
+ value:
+ type: https://open.bot/errors/organization-not-found
+ title: Organization not found.
+ status: 404
+ detail: Couldn't find that organization.
+ code: ORGANIZATION_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ team:
+ value:
+ type: https://open.bot/errors/team-not-found
+ title: Team not found.
+ status: 404
+ detail: Couldn't find that team.
+ code: TEAM_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ TeamForbidden:
+ description: 'The caller may not change this team: they are neither an owner or an admin of the organization nor one of the team''s maintainers. Or the team comes from the company''s directory, which is where it is changed.'
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/Problem'
+ examples:
+ notAllowed:
+ value:
+ type: https://open.bot/errors/permission-denied
+ title: Permission denied.
+ status: 403
+ detail: Only an admin of this organization or a maintainer of this team can change it.
+ code: PERMISSION_DENIED
+ category: permission
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ directory:
+ value:
+ type: https://open.bot/errors/permission-denied
+ title: Permission denied.
+ status: 403
+ detail: This team comes from your company's directory. Change its people there.
+ code: PERMISSION_DENIED
+ category: permission
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ InvalidTeamMember:
+ description: The role is missing or malformed, or the Idempotency-Key is.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/Problem'
+ examples:
+ role:
+ value:
+ type: https://open.bot/errors/validation-error
+ title: Request validation failed.
+ status: 400
+ detail: A role of maintainer or member is required.
+ code: VALIDATION_ERROR
+ category: validation
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ TeamOrPersonNotFound:
+ description: The organization or the team does not exist or is not visible to the caller, or the person is not a member of the organization.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/Problem'
+ examples:
+ team:
+ value:
+ type: https://open.bot/errors/team-not-found
+ title: Team not found.
+ status: 404
+ detail: Couldn't find that team.
+ code: TEAM_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ person:
+ value:
+ type: https://open.bot/errors/person-not-found
+ title: Person not found.
+ status: 404
+ detail: They aren't a member of this organization. Add them to the organization first.
+ code: PERSON_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
ApprovalsOwnOnly:
description: 'The caller asked about somebody else''s approvals, questions, preferences or rules, which only that person may read or change: an administrator can''t either.'
content:
@@ -36814,6 +38656,35 @@ components:
retryable: true
requestId: req_example
traceId: trace_example
+ OrganizationComputerNotFound:
+ description: The computer named is not one of the organization's Bots' computers, or the organization does not exist.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/Problem'
+ examples:
+ computer:
+ value:
+ type: https://open.bot/errors/bot-not-found
+ title: Bot not found.
+ status: 404
+ detail: Couldn't find that computer.
+ code: BOT_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ organization:
+ value:
+ type: https://open.bot/errors/organization-not-found
+ title: Organization not found.
+ status: 404
+ detail: Couldn't find that organization.
+ code: ORGANIZATION_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
ComputerBotNotFound:
description: The Bot does not exist or is not the caller's to use, a file or a control request the call names does not exist, or the organization does not.
content:
@@ -39081,11 +40952,13 @@ components:
summary: A new thread id.
value:
threadId: 6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a
+ liveThreadId: 2b503bf7-514a-8c4e-b132-3ca9b729ffeb
ConversationThreadStatusExample:
summary: A thread that is still there.
value:
threadId: 6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a
known: true
+ liveThreadId: 2b503bf7-514a-8c4e-b132-3ca9b729ffeb
TaskPageExample:
summary: One task, ready to read.
value:
@@ -39697,6 +41570,11 @@ components:
granted:
- notion/notion-fetch
- notion/notion-search
+ AppTeamGrantsExample:
+ summary: Granted to one team.
+ value:
+ teams:
+ - Tm4Qx8LpV2nWc7RbY1sKd0Ze
GiveableAppPageExample:
summary: Two apps the person could give their Bots.
value:
@@ -39976,6 +41854,7 @@ components:
ownerId: user_3f1c9a
botIds:
- general-assistant
+ usableOnYourBots: true
- slug: weekly-report
title: Weekly report
summary: Sum up the week's work for the team.
@@ -39985,6 +41864,7 @@ components:
botIds:
- general-assistant
- research-assistant
+ usableOnYourBots: false
nextCursor: null
SkillExample:
summary: A person's own skill, offered by one Bot.
@@ -39998,6 +41878,12 @@ components:
ownerId: user_3f1c9a
botIds:
- general-assistant
+ usableOnYourBots: true
+ SkillTeamGrantsExample:
+ summary: Granted to one team.
+ value:
+ teams:
+ - Tm4Qx8LpV2nWc7RbY1sKd0Ze
DevicePageLast:
summary: A person's iPhone, on one page.
value:
@@ -40455,19 +42341,21 @@ components:
value:
cancelled: true
OrganizationPageLast:
- summary: Somebody in two organizations, working in the first.
+ summary: Somebody in their own organization and one they created, working in their own.
value:
organizations:
- - id: default
- slug: default
- name: Acme
- role: admin
+ - id: Wm4pZ7tKc1Xb9RnQ2sYd6hLe
+ slug: dana
+ name: Dana's organization
+ role: owner
active: true
+ personal: true
- id: Jq3xT9mLw2Vb8RnC5sYd0fKe
slug: acme-research
name: Acme Research
role: owner
active: false
+ personal: false
canCreate: true
nextCursor: null
CreatedOrganization:
@@ -40479,6 +42367,7 @@ components:
name: Acme Research
role: owner
active: false
+ personal: false
OrganizationMemberPageLast:
summary: An organization's members, on one page.
value:
@@ -40489,23 +42378,196 @@ components:
image: null
role: owner
joinedAt: '2026-11-14T09:12:40.000Z'
+ removable: false
+ assignableRoles: []
- id: 2fn8w1c6y4tq7h0mbe3s
email: sam.ortiz@acme.com
name: Sam Ortiz
image: null
role: member
joinedAt: '2026-11-14T09:20:05.000Z'
+ removable: true
+ assignableRoles:
+ - owner
+ - admin
nextCursor: null
- AddedOrganizationMember:
- summary: Somebody added as a member.
+ RenamedOrganization:
+ summary: An organization with its new name.
+ value:
+ organization:
+ id: Jq3xT9mLw2Vb8RnC5sYd0fKe
+ slug: acme-research
+ name: Acme Research Lab
+ role: owner
+ active: true
+ personal: false
+ PromotedOrganizationMember:
+ summary: A member an owner has made an owner too.
value:
member:
id: 2fn8w1c6y4tq7h0mbe3s
email: sam.ortiz@acme.com
name: Sam Ortiz
image: null
- role: member
+ role: owner
joinedAt: '2026-11-14T09:20:05.000Z'
+ removable: true
+ assignableRoles:
+ - admin
+ - member
+ OrganizationInvitationPageLast:
+ summary: One invitation waiting and one that expired.
+ value:
+ invitations:
+ - id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11
+ email: sam.ortiz@acme.com
+ role: member
+ status: pending
+ invitedBy:
+ name: Dana Whitfield
+ email: dana.whitfield@acme.com
+ createdAt: '2026-11-15T09:20:05.000Z'
+ expiresAt: '2026-11-22T09:20:05.000Z'
+ - id: 0c2d7a53-1f4e-4f0a-8a57-3d1b2c9e7f42
+ email: lee.park@acme.com
+ role: admin
+ status: expired
+ invitedBy:
+ name: Dana Whitfield
+ email: dana.whitfield@acme.com
+ createdAt: '2026-11-01T09:20:05.000Z'
+ expiresAt: '2026-11-08T09:20:05.000Z'
+ nextCursor: null
+ CreatedOrganizationInvitation:
+ summary: An invitation OpenBot could not email, so the inviter passes the link on.
+ value:
+ invitation:
+ id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11
+ email: sam.ortiz@acme.com
+ role: member
+ status: pending
+ invitedBy:
+ name: Dana Whitfield
+ email: dana.whitfield@acme.com
+ createdAt: '2026-11-15T09:20:05.000Z'
+ expiresAt: '2026-11-22T09:20:05.000Z'
+ delivery: link
+ InvitationPageLast:
+ summary: One invitation waiting for the caller.
+ value:
+ invitations:
+ - id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11
+ organization:
+ id: Jq3xT9mLw2Vb8RnC5sYd0fKe
+ slug: acme-research
+ name: Acme Research
+ role: member
+ status: pending
+ invitedBy:
+ name: Dana Whitfield
+ email: dana.whitfield@acme.com
+ createdAt: '2026-11-15T09:20:05.000Z'
+ expiresAt: '2026-11-22T09:20:05.000Z'
+ nextCursor: null
+ WaitingInvitation:
+ summary: An invitation the caller can still answer.
+ value:
+ invitation:
+ id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11
+ organization:
+ id: Jq3xT9mLw2Vb8RnC5sYd0fKe
+ slug: acme-research
+ name: Acme Research
+ role: member
+ status: pending
+ invitedBy:
+ name: Dana Whitfield
+ email: dana.whitfield@acme.com
+ createdAt: '2026-11-15T09:20:05.000Z'
+ expiresAt: '2026-11-22T09:20:05.000Z'
+ JoinedOrganization:
+ summary: The organization somebody joined by accepting an invitation.
+ value:
+ organization:
+ id: Jq3xT9mLw2Vb8RnC5sYd0fKe
+ slug: acme-research
+ name: Acme Research
+ role: member
+ active: false
+ personal: false
+ TeamPageLast:
+ summary: An organization's teams, on one page.
+ value:
+ teams:
+ - id: Tm4Qx8LpV2nWc7RbY1sKd0Ze
+ name: Sales
+ description: Everybody who sells.
+ parentTeamId: null
+ source: openbot
+ memberCount: 2
+ role: maintainer
+ canManage: true
+ canMove: true
+ canDelete: true
+ createdAt: '2026-11-15T09:12:40.000Z'
+ - id: Fn2Wc6Yt4Qh7M0be3sKq8xLp
+ name: Finance
+ description: null
+ parentTeamId: null
+ source: directory
+ memberCount: 1
+ role: null
+ canManage: false
+ canMove: true
+ canDelete: false
+ createdAt: '2026-11-15T09:20:05.000Z'
+ canCreate: true
+ nextCursor: null
+ CreatedTeam:
+ summary: A team made in OpenBot.
+ value:
+ team:
+ id: Tm4Qx8LpV2nWc7RbY1sKd0Ze
+ name: Sales
+ description: Everybody who sells.
+ parentTeamId: null
+ source: openbot
+ memberCount: 0
+ role: null
+ canManage: true
+ canMove: true
+ canDelete: true
+ createdAt: '2026-11-15T09:12:40.000Z'
+ TeamMemberPageLast:
+ summary: A team's people, on one page.
+ value:
+ members:
+ - id: 8kq2m4x7p1rvz3a9c5d0
+ email: dana.whitfield@acme.com
+ name: Dana Whitfield
+ image: null
+ role: maintainer
+ isCaller: true
+ joinedAt: '2026-11-15T09:13:02.000Z'
+ - id: 2fn8w1c6y4tq7h0mbe3s
+ email: sam.ortiz@acme.com
+ name: Sam Ortiz
+ image: null
+ role: member
+ isCaller: false
+ joinedAt: '2026-11-15T09:20:05.000Z'
+ nextCursor: null
+ AddedTeamMember:
+ summary: Somebody put in a team.
+ value:
+ member:
+ id: 2fn8w1c6y4tq7h0mbe3s
+ email: sam.ortiz@acme.com
+ name: Sam Ortiz
+ image: null
+ role: member
+ isCaller: false
+ joinedAt: '2026-11-15T09:20:05.000Z'
ApprovalPageExample:
summary: One approval waiting, on the last page.
value:
@@ -41210,7 +43272,7 @@ components:
assignedGroups: []
nextCursor: null
TeamBotExample:
- summary: Published to the whole team, seen by a teammate.
+ summary: Published to everyone in the organization, seen by one of them.
value:
teamBot:
botId: agent_9b1c6f0e-7f0e-4c1e-9d55-2f4a8c1b6e21
diff --git a/api/openapi/accounts.yaml b/api/openapi/accounts.yaml
index e18d7cfbda..d06cf464cf 100644
--- a/api/openapi/accounts.yaml
+++ b/api/openapi/accounts.yaml
@@ -165,14 +165,22 @@ paths:
operationId: revokePersonAccess
summary: Remove a person's access
description: >-
- Stop a person from using OpenBot: their address can't sign in again,
- and the sessions, API keys and app sign-ins they hold end at once.
- They keep their record and their history, and restoring their access
- lets them sign in again. Their connected credentials are retired too.
- Only an administrator may do this, never to themselves, and never to
- somebody the deployment's configuration names as an administrator.
- Removing somebody already removed retires anything left and records
- nothing new.
+ Remove a person from the organization. Where everybody has an
+ organization of their own (an OpenBot whose list of organizations
+ answers canCreate true), this ends their membership of this
+ organization alone: they lose its Bots and conversations from their
+ next request, and their account, sessions, API keys, their own
+ organization and any other they belong to are unchanged. Restoring
+ them puts the membership back with its role and teams. Where OpenBot
+ keeps one organization, it stops the person using OpenBot: their
+ address can't sign in again, and the sessions, API keys and app
+ sign-ins they hold end at once; restoring their access lets them sign
+ in again. Either way they keep their record and their history, and the
+ credentials they connected here are retired. Only an administrator may
+ do this, never to themselves, never to somebody the deployment's
+ configuration names as an administrator, and never to the
+ organization's owner. Removing somebody already removed retires
+ anything left and records nothing new.
security:
- webSession: []
- appOAuth: [people:write]
@@ -215,10 +223,14 @@ paths:
operationId: restorePersonAccess
summary: Give a person their access back
description: >-
- Let a removed person sign in again. What ended when they were removed
- stays ended: they sign in afresh and make new API keys. Only an
- administrator may do this. Restoring somebody who was never removed
- changes nothing and records nothing.
+ Give a removed person their access back. Where everybody has an
+ organization of their own, this puts back their membership of this
+ organization with the role and teams it had; their sessions and API
+ keys, which were never ended, work here again from their next request.
+ Where OpenBot keeps one organization, it lets them sign in again, and
+ what ended when they were removed stays ended: they sign in afresh and
+ make new API keys. Only an administrator may do this. Restoring
+ somebody who was never removed changes nothing and records nothing.
security:
- webSession: []
- appOAuth: [people:write]
@@ -597,8 +609,8 @@ paths:
operationId: createApiKey
summary: Make an API key
description: >-
- Make an API key that acts as the person, inside this organization,
- on the API only. The key itself is in this answer and never again:
+ Make an API key that acts as the person, in every organization they
+ are a member of, on the API. The key itself is in this answer and never again:
OpenBot keeps only a hash of it. Only the person themselves may make
one, signed in to OpenBot: a key can never make another key, and
neither can an app's sign-in. A key ends when it expires, when it is
diff --git a/api/openapi/admin-settings.yaml b/api/openapi/admin-settings.yaml
index 4d939468d4..bff75128f2 100644
--- a/api/openapi/admin-settings.yaml
+++ b/api/openapi/admin-settings.yaml
@@ -14,7 +14,11 @@ paths:
Return what this OpenBot offers and how people sign in to it: the
edition, the features the apps draw, and the sign-in options. Anybody
may read it, signed in or not, because the sign-in screen reads it
- first. It names no identity provider and no version: only whether
+ first. Signed in, it is answered in an organization the caller is a
+ member of, and an organization they are not in, the organization
+ `default` included, answers exactly as one that does not exist. Nobody
+ signed in reads it in the organization `default`. It names no identity
+ provider and no version: only whether
single sign-on is set up and required.
x-openbot-singleton: true
security:
@@ -46,14 +50,16 @@ paths:
operationId: getOrganizationSettings
summary: Read the organization's settings
description: >-
- Return the settings an administrator sets for everybody: single
- sign-on, recording computer actions, stopping idle computers, the
- model and app allowlists, sharing learned skills, check-ins a day and
- choosing a model. Beside them, read only, what an administrator needs
- to set them: the model OpenBot runs on, the directory groups, the apps
- an allowlist can name, the hosts every computer may reach, and whether
- SCIM and OpenTelemetry are set up. Only an administrator may read
- them.
+ Return the settings the organization's administrators set for its
+ members: single sign-on, recording computer actions, stopping idle
+ computers, the model and app allowlists, sharing learned skills,
+ check-ins a day and choosing a model. Each organization has its own,
+ and a new one starts with OpenBot's defaults. Beside them, read only,
+ what an administrator needs to set them: the model OpenBot runs on,
+ the directory groups of the organization's members, the apps an
+ allowlist can name, the hosts every computer may reach, and whether
+ SCIM and OpenTelemetry are set up. Only an administrator of the
+ organization may read them.
x-openbot-singleton: true
security:
- webSession: []
@@ -91,7 +97,10 @@ paths:
the audit trail with what it was before. Requiring single sign-on needs
an identity provider registered first, and signs out everybody who
signed in another way, apart from the administrators the deployment's
- configuration names and the caller. Only an administrator may change
+ configuration names and the caller. Requiring single sign-on applies
+ to signing in to the whole OpenBot, so it is set only in the
+ organization `default`: sending ssoRequired in any other organization
+ answers 409. Only an administrator of the organization may change
them.
security:
- webSession: []
@@ -467,8 +476,8 @@ paths:
description: >-
Return each permission switch as it applies to one person, so the apps
hide what they may not use. The caller reads their own, as me; an
- administrator reads anybody's. enforced is false where the deployment
- keeps no switches and every default applies.
+ administrator of the organization reads any member's. enforced is
+ false where this OpenBot keeps no switches and every default applies.
x-openbot-singleton: true
security:
- webSession: []
@@ -508,9 +517,12 @@ paths:
operationId: stopPersonComputers
summary: Stop a person's computers
description: >-
- Stop every Bot computer running for one person now, and record it on
- the audit trail. Their Bots start a computer again when they next need
- one. Only an administrator may do this.
+ Stop the computers of the organization's Bots that one person owns,
+ now, and record it on the audit trail. Their Bots start a computer
+ again when they next need one. A person's own computer is stopped
+ only from the organization `default`. A person who is not a member of
+ the organization is not found (PERSON_NOT_FOUND). Only an
+ administrator of the organization may do this.
security:
- webSession: []
- appOAuth: [people:write]
@@ -803,9 +815,9 @@ paths:
operationId: getModelUsage
summary: Read which models Bots ran on
description: >-
- Return which models Bots ran on over the last days, with how many runs,
- refusals and people each had, and the newest 50 runs. Only an
- administrator may read it.
+ Return which models the organization's Bots ran on over the last days,
+ with how many runs, refusals and people each had, and the newest 50
+ runs. Only an administrator of the organization may read it.
x-openbot-singleton: true
security:
- webSession: []
@@ -853,9 +865,10 @@ paths:
operationId: listComputerActions
summary: List recorded computer actions
description: >-
- Return one page of the actions recorded on Bot computers while
- recording computer actions is on, newest first. Records are kept for
- actionRecordRetentionDays. Only an administrator may read them. A
+ Return one page of the actions recorded on the organization's Bots'
+ computers while recording computer actions is on, newest first.
+ Records are kept for actionRecordRetentionDays. Only an administrator
+ of the organization may read them. A
missing cursor starts at the newest and nextCursor null ends the list.
security:
- webSession: []
@@ -985,12 +998,14 @@ components:
name: networkPolicyId
in: path
required: true
- description: organization, or group: for a directory group's.
+ description: >-
+ organization, team: for a team's, or group: for a directory
+ group's.
schema:
type: string
minLength: 1
maxLength: 206
- pattern: ^(organization|group:[^\x00]*\S[^\x00]*)$
+ pattern: ^(organization|team:[^\x00]*\S[^\x00]*|group:[^\x00]*\S[^\x00]*)$
schemas:
Deployment:
type: object
@@ -1086,9 +1101,11 @@ components:
ssoRequired:
type: boolean
description: >-
- Whether people must sign in through the organization's identity
- provider. The administrators the deployment's configuration names
- keep social sign-in as their way in.
+ Whether people must sign in through the company's identity
+ provider. It applies to signing in to the whole OpenBot, so it is
+ set only in the organization `default`. The administrators the
+ deployment's configuration names keep social sign-in as their way
+ in.
actionRecording:
type: boolean
description: Whether what Bots do on their computers is recorded, to read in computer actions.
@@ -1167,7 +1184,7 @@ components:
description: The model OpenBot's own Bots run on, when one is set.
directoryGroups:
type: array
- description: The directory groups people belong to, by name.
+ description: The directory groups the organization's members belong to, by name.
items:
type: string
apps:
@@ -1299,7 +1316,15 @@ components:
type: object
description: >-
What each directory group is set to, by the group's name. A group
- absent sets nothing. Team scopes will be added when teams arrive.
+ absent sets nothing.
+ additionalProperties:
+ type: boolean
+ teams:
+ type: object
+ description: >-
+ What each team is set to, by the team's id. A team absent sets
+ nothing. A team's switch can only turn a permission on for the
+ people in it, and in the teams beneath it.
additionalProperties:
type: boolean
CapabilityPage:
@@ -1343,7 +1368,20 @@ components:
minProperties: 1
maxProperties: 100
description: >-
- By directory group name, 1 to 200 characters. Team scopes will be added when teams arrive.
+ By directory group name, 1 to 200 characters.
+ propertyNames:
+ minLength: 1
+ maxLength: 200
+ pattern: ^[^\x00]*\S[^\x00]*$
+ additionalProperties:
+ $ref: '#/components/schemas/SwitchValue'
+ teams:
+ type: object
+ minProperties: 1
+ maxProperties: 100
+ description: >-
+ By team id. A team that is not one of this organization's is not
+ found.
propertyNames:
minLength: 1
maxLength: 200
@@ -1357,15 +1395,15 @@ components:
properties:
scopeKind:
type: string
- enum: [organization, role, group]
+ enum: [organization, role, group, team]
description: >-
- Whose switch: the organization's, a member role's, or a directory
- group's. Team scopes will be added when teams arrive.
+ Whose switch: the organization's, a member role's, a team's, or a
+ directory group's.
scopeId:
type: string
maxLength: 200
pattern: ^[^\x00]*$
- description: Empty for the organization; admin or member for a role; a directory group's name for a group. Team scopes will be added when teams arrive.
+ description: Empty for the organization; admin or member for a role; a team's id for a team; a directory group's name for a group.
capability:
$ref: '#/components/schemas/CapabilityId'
allowed:
@@ -1407,15 +1445,15 @@ components:
properties:
scopeKind:
type: string
- enum: [organization, role, group]
+ enum: [organization, role, group, team]
description: >-
- Whose switch: the organization's, a member role's, or a directory
- group's. Team scopes will be added when teams arrive.
+ Whose switch: the organization's, a member role's, a team's, or a
+ directory group's.
scopeId:
type: string
maxLength: 200
pattern: ^[^\x00]*$
- description: Empty for the organization; admin or member for a role; a directory group's name for a group. Team scopes will be added when teams arrive.
+ description: Empty for the organization; admin or member for a role; a team's id for a team; a directory group's name for a group.
capability:
type: string
maxLength: 100
@@ -1494,13 +1532,13 @@ components:
properties:
scopeKind:
type: string
- enum: [organization, role, group]
+ enum: [organization, role, group, team]
description: >-
- Whose switch: the organization's, a member role's, or a directory
- group's. Team scopes will be added when teams arrive.
+ Whose switch: the organization's, a member role's, a team's, or a
+ directory group's.
scopeId:
type: string
- description: Empty for the organization; admin or member for a role; a directory group's name for a group.
+ description: Empty for the organization; admin or member for a role; a team's id for a team; a directory group's name for a group.
capability:
type: string
allowed:
@@ -1513,10 +1551,10 @@ components:
type: boolean
decidedBy:
type: string
- enum: [default, organization, role, group]
+ enum: [default, organization, role, group, team]
scopeId:
type: string
- description: The role or group that decided it. Empty otherwise.
+ description: The role, the group's name or the team's id that decided it. Empty otherwise.
CapabilityPreview:
type: object
required: [check, people, counts, activity, warning]
@@ -1655,16 +1693,16 @@ components:
id:
type: string
description: >-
- organization, or group: for a directory group. Team scopes will be added when teams arrive.
+ organization, team: for a team, or group: for a directory group.
scopeKind:
type: string
- enum: [organization, group]
+ enum: [organization, group, team]
description: >-
- Whose policy: the organization's, or a directory group's.
- Team scopes will be added when teams arrive.
+ Whose policy: the organization's, a team's, or a directory
+ group's.
scopeId:
type: string
- description: The directory group's name. Empty for the organization.
+ description: The team's id, or the directory group's name. Empty for the organization.
mode:
$ref: '#/components/schemas/NetworkMode'
rules:
@@ -1719,15 +1757,15 @@ components:
properties:
scopeKind:
type: string
- enum: [organization, group]
+ enum: [organization, group, team]
description: >-
- Whose policy: the organization's, or a directory group's.
- Team scopes will be added when teams arrive.
+ Whose policy: the organization's, a team's, or a directory
+ group's.
scopeId:
type: string
maxLength: 200
pattern: ^[^\x00]*$
- description: The directory group's name. Empty for the organization.
+ description: The team's id, or the directory group's name. Empty for the organization.
mode:
$ref: '#/components/schemas/NetworkMode'
rules:
@@ -1961,12 +1999,24 @@ components:
SettingsConflict:
description: >-
Single sign-on can't be required before an identity provider is
- registered, or the Idempotency-Key was used for a different request.
+ registered, ssoRequired was sent in an organization other than
+ `default`, or the Idempotency-Key was used for a different request.
content:
application/problem+json:
schema:
$ref: './common.yaml#/components/schemas/Problem'
examples:
+ notTheFirstOrganization:
+ value:
+ type: https://open.bot/errors/conflict
+ title: The request conflicts with the current state.
+ status: 409
+ detail: Requiring SSO applies to signing in to this OpenBot as a whole, so it can't be set for one organization.
+ code: CONFLICT
+ category: conflict
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
noProvider:
value:
type: https://open.bot/errors/conflict
diff --git a/api/openapi/approvals.yaml b/api/openapi/approvals.yaml
index 5f56496239..c854baf0f7 100644
--- a/api/openapi/approvals.yaml
+++ b/api/openapi/approvals.yaml
@@ -3970,7 +3970,7 @@ components:
additionalProperties: false
description: >-
One action a Bot might take. Who: a Bot, and either the person whose
- accounts it runs on or a directory group, for any member of it. What
+ accounts it runs on or a team or directory group, for any member of it. What
starts the run. Then either an app's tool, or something on the Bot's
computer. A field that does not apply is empty.
required:
@@ -3995,7 +3995,9 @@ components:
description: The person's id. Empty when a group is named.
group:
type: string
- description: A directory group's name. Empty when a person is named.
+ description: >-
+ A directory group's name, or team: for one of the
+ organization's teams. Empty when a person is named.
initiator:
$ref: '#/components/schemas/WhatIfInitiator'
surface:
@@ -4265,6 +4267,19 @@ components:
description: The directory groups, by name.
items:
type: string
+ teams:
+ type: array
+ description: >-
+ The organization's teams. An action names one in group, as
+ team:.
+ items:
+ type: object
+ required: [id, name]
+ properties:
+ id:
+ type: string
+ name:
+ type: string
apps:
type: array
items:
@@ -4295,19 +4310,19 @@ components:
enum: [owner, people, team]
description: >-
Who may steer a Bot that uses a shared app's account: only the Bot's
- owner, the people and directory groups named, or everybody in the
- organization.
+ owner, the people, teams and directory groups named, or everyone in
+ the organization (team).
SharedUseMember:
type: object
- description: One person or directory group an audience names.
+ description: One person, team or directory group an audience names.
required: [kind, value]
properties:
kind:
type: string
- enum: [user, group]
+ enum: [user, group, team]
value:
type: string
- description: The person's id, or the directory group's name.
+ description: The person's id, the team's id, or the directory group's name.
SharedUseApproval:
type: object
description: >-
@@ -4323,7 +4338,7 @@ components:
description: Whether runs started by outside input are covered.
members:
type: array
- description: The people and groups named, when the audience is people. Empty otherwise.
+ description: The people, teams and groups named, when the audience is people. Empty otherwise.
items:
$ref: '#/components/schemas/SharedUseMember'
SharedUseRequest:
diff --git a/api/openapi/apps.yaml b/api/openapi/apps.yaml
index f99099481e..9450ac56d6 100644
--- a/api/openapi/apps.yaml
+++ b/api/openapi/apps.yaml
@@ -1,4 +1,4 @@
-# Apps: the apps this OpenBot has added for its Bots to use, the directory of apps it can add, and
+# Apps: the apps an organization has added for its Bots to use, the directory of apps it can add, and
# how apps are set up here. Also the parts every apps area shares (an app's id, the shared-account
# approval, and the refusals about an app), listed in common.yaml for the connections and Bot grants
# areas to use.
@@ -14,11 +14,12 @@ paths:
operationId: listApps
summary: List the apps added here
description: >-
- Return one page of the apps this OpenBot has added for its Bots: the
- ones from its catalogue, the ones added from the app directory, and
- servers added by their address. Each app comes with the actions it
- offers and the Bots that may use each one. Anybody signed in may read
- them. Ordered by title, ignoring case, then by id. A missing cursor
+ Return one page of the apps the organization has added for its Bots:
+ the ones from OpenBot's catalogue, the ones added from the app
+ directory, and servers added by their address. Each organization has
+ its own apps, and an app added in one is not in another. Each app
+ comes with the actions it offers and the Bots that may use each one.
+ Any member of the organization may read them. Ordered by title, ignoring case, then by id. A missing cursor
starts at the first page and nextCursor null ends the list.
security:
- webSession: []
@@ -309,12 +310,14 @@ paths:
operationId: deleteApp
summary: Remove an app
description: >-
- Remove an app for everybody. Every person's connection to it is ended,
+ Remove an app for everybody in the organization. Every member's
+ connection to it is ended,
at the app's own service too, every Bot stops being able to use its
actions, and a server's key is retired. Recorded on the audit trail.
Removing can stop partway when the service behind the app doesn't
answer. The app then stays, and removing it again is safe and finishes
- the job. Routines can't be removed. Only an administrator may.
+ the job. Routines can't be removed. Only an administrator of the
+ organization may.
security:
- webSession: []
- appOAuth: [apps:write]
@@ -401,7 +404,8 @@ paths:
summary: Choose whose account an app acts in
description: >-
Choose whose account an app from the directory acts in: each person's
- own (personal), or one account OpenBot holds for everybody (shared).
+ own (personal), or one account OpenBot holds for everybody in the
+ organization (shared).
Every account the switch leaves behind is ended at the app's service
first. Nothing changes unless all of them ended, and the problem's
problems then names each account that didn't. Switching to shared
@@ -708,9 +712,11 @@ components:
additionalProperties: false
description: >-
Who may have a Bot use an app's one shared account, approved by an
- administrator: only the Bot's owner, named people and directory
- groups, or everybody; and whether the Bot may act on what people
- outside the organization send it.
+ administrator: only the Bot's owner, named people, teams and
+ directory groups, or everyone in the organization (team); and whether
+ the Bot may act on what people outside the organization send it. A
+ member of kind team names one of the organization's teams by id; a
+ team of another organization is not found.
required:
- audience
- outsideInput
@@ -739,6 +745,7 @@ components:
enum:
- user
- group
+ - team
value:
type: string
minLength: 1
@@ -815,7 +822,8 @@ components:
App:
type: object
description: >-
- An app this OpenBot has added for its Bots, with the actions it offers.
+ An app the organization has added for its Bots, with the actions it
+ offers.
No secret is ever part of an app: hasCredential says whether a key or
client is kept for it.
required:
@@ -909,7 +917,8 @@ components:
- type: 'null'
description: >-
Whose account an app from the directory acts in: each person's own,
- or one account OpenBot holds for everybody. Null for an app with no
+ or one account OpenBot holds for everybody in the organization.
+ Null for an app with no
account at all, and for any other app.
sharedAccountConnected:
type: boolean
@@ -1095,7 +1104,7 @@ components:
AppAccountMode:
type: string
enum: [personal, shared]
- description: Each person's own account, or one account OpenBot holds for everybody.
+ description: Each person's own account, or one account OpenBot holds for everybody in the organization.
AppAccountModeRequest:
type: object
additionalProperties: false
@@ -1138,7 +1147,7 @@ components:
enum: [person, deployment]
description: >-
Whose accounts they are: people's own (person), or the one
- OpenBot holds for everybody (deployment).
+ OpenBot holds for everybody in the organization (deployment).
count:
type: integer
minimum: 0
diff --git a/api/openapi/audit-events.yaml b/api/openapi/audit-events.yaml
index b8d357da2a..a3345b79e1 100644
--- a/api/openapi/audit-events.yaml
+++ b/api/openapi/audit-events.yaml
@@ -11,14 +11,21 @@ paths:
operationId: listAuditEvents
summary: List audit events
description: >-
- Return one page of the audit trail, newest first, narrowed by the
- filters given. Each filter narrows the events, and a filter that takes
+ Return one page of the organization's audit trail, newest first,
+ narrowed by the filters given. Each organization has its own trail,
+ and an event is on the trail of the organization it happened in. What
+ happens to the organization itself is on its trail too:
+ organization.created, organization.renamed,
+ organization.member_invited, organization.invitation_canceled,
+ organization.member_joined, organization.member_removed and
+ organization.member_role_changed.
+ Each filter narrows the events, and a filter that takes
several values separated by commas matches any of them. A value that
names nothing in the trail matches no event rather than being refused.
A missing cursor starts at the newest event and nextCursor null ends
the list. A cursor belongs to the filters that made it, so changing a
filter starts again without one; limit may change from page to page.
- Only an administrator may read the trail.
+ Only an administrator of the organization may read its trail.
security:
- webSession: []
- appOAuth: [audit-events:read]
@@ -80,7 +87,8 @@ paths:
events; when more match, OpenBot-Export-Truncated says how many it
holds, and narrowing the dates exports the rest. A cell a spreadsheet
would run as a formula starts with an apostrophe. Each export is
- recorded on the trail. Only an administrator may export the trail.
+ recorded on the trail. Only an administrator of the organization may
+ export its trail.
x-openbot-singleton: true
security:
- webSession: []
@@ -262,7 +270,8 @@ components:
in: query
description: >-
Events of any of these types, separated by commas, such as
- computer.action_refused,mcp.call_rejected.
+ computer.action_refused,mcp.call_rejected or
+ organization.member_invited,organization.member_removed.
schema:
$ref: '#/components/schemas/AuditFilterText'
AuditExcludedEventTypes:
diff --git a/api/openapi/bot-grants.yaml b/api/openapi/bot-grants.yaml
index 64bedab0a9..53c03ef77a 100644
--- a/api/openapi/bot-grants.yaml
+++ b/api/openapi/bot-grants.yaml
@@ -586,6 +586,99 @@ paths:
$ref: './common.yaml#/components/responses/AppDirectoryUnavailable'
default:
$ref: './common.yaml#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/apps/{appId}/team-grants:
+ parameters:
+ - $ref: './common.yaml#/components/parameters/OrganizationId'
+ - $ref: './common.yaml#/components/parameters/AppId'
+ get:
+ tags: [Bot grants]
+ operationId: getAppTeamGrants
+ summary: Read the teams the app is granted to
+ description: >-
+ Return the teams the app is granted to, by id. A person in one of those teams, or in a team beneath one, may give the app to a Bot they own without an access request, and the Bot may use it only while they stay in such a team; nobody else in the organization may give it to their own Bot. Only an admin
+ of the organization may read them.
+ x-openbot-singleton: true
+ security:
+ - webSession: []
+ - appOAuth: [bot-grants:read]
+ - apiKey: []
+ responses:
+ '200':
+ description: The teams the app is granted to.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/AppTeamGrants'
+ examples:
+ granted:
+ $ref: '#/components/examples/AppTeamGrantsExample'
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/AppOrTeamNotFound'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ put:
+ tags: [Bot grants]
+ operationId: replaceAppTeamGrants
+ summary: Grant an app to teams
+ description: >-
+ Grant the app to exactly these teams of the organization, taking it
+ from any team left out. An empty list takes it from every team.
+ A person in one of those teams, or in a team beneath one, may give the app to a Bot they own without an access request, and the Bot may use it only while they stay in such a team; nobody else in the organization may give it to their own Bot. A team of another organization is not found. Only an admin
+ of the organization may do this. Recorded on the audit trail.
+ security:
+ - webSession: []
+ - appOAuth: [bot-grants:write]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/AppTeamGrantsInput'
+ examples:
+ oneTeam:
+ value:
+ teams: [Tm4Qx8LpV2nWc7RbY1sKd0Ze]
+ responses:
+ '200':
+ description: The teams the app is now granted to.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/AppTeamGrants'
+ examples:
+ granted:
+ $ref: '#/components/examples/AppTeamGrantsExample'
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/AppOrTeamNotFound'
+ '409':
+ $ref: './common.yaml#/components/responses/IdempotencyConflict'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
/api/v2/organizations/{organizationId}/people/{personId}/giveable-apps:
parameters:
- $ref: './common.yaml#/components/parameters/OrganizationId'
@@ -641,8 +734,9 @@ paths:
operationId: listAppAccessRequests
summary: List requests for apps
description: >-
- Return one page of the requests waiting for an administrator: all of
- them for an administrator, and only their own for anybody else. appId
+ Return one page of the organization's requests waiting for an
+ administrator: all of them for an administrator of the organization,
+ and only their own for anybody else. appId
narrows them to one app. Newest first, and by id among requests made
at the same moment. A missing cursor starts at the first page and
nextCursor null ends the list.
@@ -1276,6 +1370,30 @@ components:
oneOf:
- $ref: '#/components/schemas/BotGrantReplayReport'
- type: 'null'
+ AppTeamGrants:
+ type: object
+ description: The teams the app is granted to.
+ required: [teams]
+ properties:
+ teams:
+ type: array
+ description: Each team's id, in order.
+ items:
+ type: string
+ AppTeamGrantsInput:
+ type: object
+ additionalProperties: false
+ required: [teams]
+ properties:
+ teams:
+ type: array
+ maxItems: 100
+ description: The id of each team of this organization to grant it to.
+ items:
+ type: string
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
AppAccessRequestKind:
type: string
description: >-
@@ -1648,6 +1766,37 @@ components:
retryable: false
requestId: req_example
traceId: trace_example
+ AppOrTeamNotFound:
+ description: >-
+ OpenBot has no app by that id, a team named is not one of this
+ organization's, or the organization does not exist.
+ content:
+ application/problem+json:
+ schema:
+ $ref: './common.yaml#/components/schemas/Problem'
+ examples:
+ app:
+ value:
+ type: https://open.bot/errors/app-not-found
+ title: App not found.
+ status: 404
+ detail: OpenBot has no app called asana.
+ code: APP_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ team:
+ value:
+ type: https://open.bot/errors/team-not-found
+ title: Team not found.
+ status: 404
+ detail: Couldn't find that team.
+ code: TEAM_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
BotGrantNotFound:
description: >-
The Bot isn't one the caller can use, the Bot doesn't have that, or the
@@ -2054,6 +2203,10 @@ components:
summary: Notion's reads, taken back.
value:
takenBack: [notion/notion-fetch, notion/notion-search]
+ AppTeamGrantsExample:
+ summary: Granted to one team.
+ value:
+ teams: [Tm4Qx8LpV2nWc7RbY1sKd0Ze]
GiveableAppPageExample:
summary: Two apps the person could give their Bots.
value:
diff --git a/api/openapi/bots.yaml b/api/openapi/bots.yaml
index 00b055203c..2c41f3da21 100644
--- a/api/openapi/bots.yaml
+++ b/api/openapi/bots.yaml
@@ -14,9 +14,15 @@ paths:
Return one page of the Bots the caller can see: theirs, the ones shared
with them, the ones assigned to them and the ones that come with
OpenBot, oldest first, and by id among Bots made at the same moment.
- hidden=true lists only the Bots the caller hid from their own list
- instead. A missing cursor starts at the first page and nextCursor null
- ends the list.
+ Somebody else's private Bot is never among them, an admin's list
+ included. hidden=true lists only the Bots the caller hid from their own
+ list instead. scope=organization lists every Bot in the organization,
+ people's private Bots included, for an admin's screens that decide what
+ Bots may hold; it is refused to anybody who is not an admin of the
+ organization. Somebody else's private Bot comes withheld there: its
+ name and avatar, and nothing from inside it (see the Bot's withheld).
+ A missing cursor starts at the first page and nextCursor null ends the
+ list.
security:
- webSession: []
- appOAuth: [bots:read]
@@ -28,6 +34,15 @@ paths:
schema:
type: boolean
default: false
+ - name: scope
+ in: query
+ description: >-
+ Whose Bots: caller, the Bots the caller can see; organization, every
+ Bot in the organization, for an admin of it only.
+ schema:
+ type: string
+ enum: [caller, organization]
+ default: caller
- $ref: './common.yaml#/components/parameters/Limit'
- $ref: './common.yaml#/components/parameters/Cursor'
responses:
@@ -1081,7 +1096,8 @@ paths:
description: >-
Return one page of the published Bots the caller may use or manages:
their own publications, the ones published to them by name, to a
- group they are in or to the whole team, and the ones an administrator
+ group or team they are in or to everyone in the organization, and the
+ ones an administrator
assigned them. An administrator sees every one. Who a Team Bot reaches
(people, groups and assignments) is shown only to its owner and
administrators. Ordered by name, then the Bot's id. A missing cursor
@@ -1161,13 +1177,14 @@ paths:
put:
tags: [Team Bots]
operationId: publishTeamBot
- summary: Publish a Bot to the team
+ summary: Publish a Bot to everyone in the organization, or to some of them
description: >-
- Publish one of the caller's own Bots to the whole team, or to named
- people and directory groups, or change who it is published to. Each
- person's conversations with it are private to them; its owner can't
- read them. Needs the caller's Team Bots switch, and a Bot with a real
- name and a description, which is how teammates tell it apart. Every
+ Publish one of the caller's own Bots to everyone in the organization,
+ or to named people, teams and directory groups, or change who it is
+ published to. Each person's conversations with it are private to them;
+ its owner can't read them. Needs the caller's Team Bots switch, and a
+ Bot with a real name and a description, which is how the people it is
+ published to tell it apart. Every
person named must have signed in here. Publishing can widen who
reaches the shared app accounts the Bot uses, and the answer says
which an administrator still has to approve.
@@ -1185,7 +1202,7 @@ paths:
$ref: '#/components/schemas/TeamBotPublication'
examples:
team:
- summary: To the whole team.
+ summary: To everyone in the organization.
value:
audience: team
people:
@@ -1226,8 +1243,8 @@ paths:
operationId: unpublishTeamBot
summary: Unpublish a Team Bot
description: >-
- Stop publishing a Bot: teammates can't use it until it is published
- again, and its assignments wait, doing nothing. Its owner or an
+ Stop publishing a Bot: the people it was published to can't use it
+ until it is published again, and its assignments wait, doing nothing. Its owner or an
administrator may unpublish it. Unpublishing a Bot that is not
published changes nothing.
security:
@@ -1434,7 +1451,8 @@ components:
required: true
description: >-
A directory group, by the name the identity provider gives it, or *
- for everybody.
+ for everybody. A team is written team: followed by the team's id, as
+ in team:Tm4Qx8LpV2nWc7RbY1sKd0Ze.
schema:
type: string
minLength: 1
@@ -1502,6 +1520,16 @@ components:
systemOwned:
type: boolean
description: Whether it comes with OpenBot rather than belonging to a person.
+ packageBotId:
+ type: [string, 'null']
+ readOnly: true
+ description: >-
+ Which of the Bots an OpenBot starts with this one is, so a client
+ recognises it in whichever organization it is in. It is the id
+ that Bot has in the install package: the same as id in the
+ organization `default`, and the package's id on another
+ organization's copy, whose own id is generated. Null for a Bot
+ somebody made. Never accepted when a Bot is created or changed.
endpoint:
type: [string, 'null']
description: >-
@@ -1541,6 +1569,16 @@ components:
description: >-
Whether the caller created it. Separate from canManage, which is
also true for an administrator on everybody's Bots.
+ withheld:
+ type: boolean
+ description: >-
+ Whether it is somebody else's private Bot, listed for an admin's
+ screens (listBots with scope=organization) and nothing more. Such
+ a Bot carries its id, name, avatar and the caller's own state with
+ it only: title and roleDescription are empty, endpoint is null,
+ instructions and framework are absent, hasAuth, hasCallbackToken,
+ isolated, builtIn, runsOnOpenBotModel, keyFromOpenBot and canManage
+ are false. Absent or false on every other Bot.
assignedToMe:
type: boolean
description: Whether an administrator assigned this Bot to the caller.
@@ -2121,12 +2159,14 @@ components:
TeamBotAudience:
type: string
enum: [team, people]
- description: team is everybody in the organization; people is the people and groups named.
+ description: >-
+ team is everyone in the organization; people is the people, teams and
+ groups named.
TeamBot:
type: object
description: >-
- A Bot published to the team, as the caller sees it. Who it reaches
- (people, groups and assignedGroups) is present only for its owner and
+ A published Bot, as the caller sees it. Who it reaches (people, teams,
+ groups and assignedGroups) is present only for its owner and
administrators.
required:
- botId
@@ -2161,8 +2201,8 @@ components:
visibleToTeam:
type: boolean
description: >-
- False while its name or description would leave teammates unable
- to tell it apart, so they can't see it.
+ False while its name or description would leave the people it is
+ published to unable to tell it apart, so they can't see it.
people:
type: array
description: The people it is published to, by email.
@@ -2173,6 +2213,11 @@ components:
description: The directory groups it is published to.
items:
type: string
+ teams:
+ type: array
+ description: The teams it is published to, by each team's id.
+ items:
+ type: string
assignedGroups:
type: array
description: The directory groups an administrator assigned it to; * is everybody.
@@ -2220,6 +2265,19 @@ components:
items:
type: string
maxLength: 200
+ teams:
+ type: array
+ maxItems: 100
+ description: >-
+ With people, the teams to publish to, by each team's id. Every
+ one must be a team of this organization. The people in a team,
+ and in the teams under it, can use the Bot, and nobody else in
+ the organization can.
+ items:
+ type: string
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
PublishedTeamBot:
type: object
required: [teamBot, sharedApps]
@@ -2671,7 +2729,7 @@ components:
assignedGroups: []
nextCursor: null
TeamBotExample:
- summary: Published to the whole team, seen by a teammate.
+ summary: Published to everyone in the organization, seen by one of them.
value:
teamBot:
botId: agent_9b1c6f0e-7f0e-4c1e-9d55-2f4a8c1b6e21
diff --git a/api/openapi/common.yaml b/api/openapi/common.yaml
index 172c8ffb29..5ef3decf22 100644
--- a/api/openapi/common.yaml
+++ b/api/openapi/common.yaml
@@ -27,10 +27,34 @@ info:
An OpenBot install holds one or more organizations, and a person may be a
- member of several. Every install has the organization `default`, which is
- where everybody starts. organizationId is an organization's id or its
- slug, and the caller must be a member of it: an organization the caller
- is not in answers exactly as one that does not exist.
+ member of several. Where an install allows more than one, everybody has
+ an organization of their own, made for them when they first sign in, and
+ joins others by invitation. Otherwise, and on an install for one person
+ with no sign-in, everybody works in the organization `default`.
+ organizationId is an organization's id or its slug, and the caller must
+ be a member of it: an organization the caller is not in answers exactly
+ as one that does not exist, `default` included.
+
+
+ A program of your own signs its requests in one of two ways. An API key
+ acts as the person who made it, in every organization they are a member
+ of, like a personal access token: the address names the organization
+ each request is for. Keys start `obk_` and are sent as
+ `Authorization: Bearer ` or in an `x-api-key` header, on /api/v2
+ and on the socket a join token is spent on (createConversationJoinToken).
+ To get a first key, sign in to OpenBot's web app, open Settings, then API
+ keys, and create one. The key is shown once. Only a person signed in to
+ the web app can make or delete keys: a key or an app's sign-in cannot.
+ An app that signs people in uses OAuth 2.1 instead, described under the
+ appOAuth security scheme: its client ids, redirect addresses, endpoints,
+ how long tokens last and the four addresses outside /api/v2 a token also
+ works at.
+
+
+ An install for one person on one computer has no sign-in. It signs
+ nobody in, so it has neither OAuth nor API keys, and the operations
+ that manage keys and sessions answer 503 with the code
+ SIGN_IN_UNAVAILABLE.
This file is the single source of truth: the clients, the server's types,
@@ -47,7 +71,7 @@ tags:
- { name: People, description: "The people in the organization: who they are, what they may do, and what is theirs alone (their standing instructions, preferences and first-run onboarding). An administrator sees everybody; anybody else sees themselves, as me." }
- { name: Linked accounts, description: "A person's accounts at other services, such as Slack and GitHub, that OpenBot knows are theirs, so a Bot answering there knows who it is talking to." }
- { name: Identity providers, description: "The companies' own identity providers registered for single sign-on, by email domain. Only an administrator manages them." }
- - { name: API keys, description: "The keys a person makes for automation. A key acts as them, inside the organization, on the API only, and only a person signed in to OpenBot can make or manage one." }
+ - { name: API keys, description: "The keys a person makes for automation. A key acts as them, in every organization they are a member of, on the API, and only a person signed in to OpenBot can make or manage one." }
- { name: Sessions, description: "Where a person is signed in to OpenBot, so they can see each browser and device and sign one out." }
- { name: Organization settings, description: "What an administrator sets for everybody, and what this OpenBot offers: sign-in, recording, idle computers, allowlists, the setup checklist, and which models Bots ran on." }
- { name: Capabilities, description: "The permission switches that decide what people may do, set for the organization, a role or a directory group, and each person's answer." }
@@ -55,9 +79,9 @@ tags:
- { name: Conversations, description: "A person's conversations with Bots. What a Bot is doing in one streams over a WebSocket, described in api/asyncapi.yaml; the operations here hand out what that socket needs." }
- { name: Tasks, description: "The work a Bot does for a person in a conversation of its own: started from something a check-in found, or handed to the Bot by another. Where a task stands is read from its conversation, never stored." }
- { name: Voice, description: "Voice calls with a conversation's Bot: how a call connects, and the calls a person saved in a conversation with their transcripts." }
- - { name: Credentials, description: "The vault: the model keys, app keys and app tokens OpenBot keeps encrypted for its Bots. A secret goes in and is never read back out. Only an administrator manages them." }
+ - { name: Credentials, description: "The organization's vault: the model keys, app keys and app tokens OpenBot keeps encrypted for its Bots. A secret goes in and is never read back out. Only an administrator manages them." }
- { name: Models, description: "The models Bots can run on, and the one a person chose for each of their conversations." }
- - { name: Apps, description: "The apps this OpenBot has added for its Bots to use, from the directory of apps it can add or by a server's address, and how apps are set up here." }
+ - { name: Apps, description: "The apps the organization has added for its Bots to use, from the directory of apps it can add or by a server's address, and how apps are set up here." }
- { name: Connections, description: "A person's connections to apps: the accounts they signed in with so their Bots can act there for them, and an app's one shared account when an administrator connects it for everybody." }
- { name: Bot grants, description: "What each Bot may use: the app actions, skills and other Bots it was given, and each app as it stands for the person asking." }
- { name: App access requests, description: "A person asking an administrator to turn an app on, give it to a Bot, or connect its shared account." }
@@ -72,6 +96,7 @@ tags:
- { name: Goals, description: "A person's goals: an outcome a Bot works toward, run on request, on a routine's schedule or when an outside event arrives through one of the goal's triggers." }
- { name: Follow-ups, description: "Work a Bot scheduled for itself to come back to later in a conversation." }
- { name: Organizations, description: "The organizations the caller is a member of, and each one's members. An organization keeps its own Bots and conversations, apart from every other's." }
+ - { name: Teams, description: "An organization's teams: named groups of its members, and each team's people. What is granted to a team is its people's to use, and nobody else's in the organization. A team is made here or kept in step with a group of the company's directory." }
- { name: Approvals, description: "What a person's Bots are waiting on them for: the actions that ask before they run, the questions a Bot asked, and what the person set for themselves about asking (their preferences, their own rules, and what they allowed for one conversation). Each person's are theirs alone." }
- { name: Approval rules, description: "The organization's approval rules: which actions every member's Bots take without asking, ask a person about first, or hand to the person. An administrator can describe rules in English, test them against what Bots already did, and save several as one change." }
- { name: Reviewer guidance, description: "What an administrator tells auto-review, in plain English: what to ask about and what is routine for the organization. Checked by an independent reading before it is saved, and never able to switch built-in safety off." }
@@ -196,6 +221,7 @@ paths:
/api/v2/organizations/{organizationId}/bots/{botId}/apps/{appId}/give: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bots~1{botId}~1apps~1{appId}~1give' }
/api/v2/organizations/{organizationId}/bots/{botId}/apps/{appId}/take-back: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bots~1{botId}~1apps~1{appId}~1take-back' }
/api/v2/organizations/{organizationId}/bots/{botId}/apps/{appId}/approve: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bots~1{botId}~1apps~1{appId}~1approve' }
+ /api/v2/organizations/{organizationId}/apps/{appId}/team-grants: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1apps~1{appId}~1team-grants' }
/api/v2/organizations/{organizationId}/people/{personId}/giveable-apps: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1giveable-apps' }
/api/v2/organizations/{organizationId}/app-access-requests: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1app-access-requests' }
/api/v2/organizations/{organizationId}/app-access-requests/{appAccessRequestId}: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1app-access-requests~1{appAccessRequestId}' }
@@ -215,6 +241,7 @@ paths:
/api/v2/organizations/{organizationId}/bots/{botId}/components/{componentId}/call: { $ref: './components.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bots~1{botId}~1components~1{componentId}~1call' }
/api/v2/organizations/{organizationId}/skills: { $ref: './skills.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1skills' }
/api/v2/organizations/{organizationId}/skills/{skillId}: { $ref: './skills.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1skills~1{skillId}' }
+ /api/v2/organizations/{organizationId}/skills/{skillId}/team-grants: { $ref: './skills.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1skills~1{skillId}~1team-grants' }
/api/v2/organizations/{organizationId}/people/{personId}/devices: { $ref: './notifications.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1devices' }
/api/v2/organizations/{organizationId}/people/{personId}/devices/{deviceId}: { $ref: './notifications.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1devices~1{deviceId}' }
/api/v2/organizations/{organizationId}/people/{personId}/destinations: { $ref: './notifications.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1destinations' }
@@ -257,6 +284,18 @@ paths:
/api/v2/organizations/{organizationId}/bots/{botId}/follow-ups/{followUpId}/cancel: { $ref: './schedules.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bots~1{botId}~1follow-ups~1{followUpId}~1cancel' }
/api/v2/people/me/organizations: { $ref: './organizations.yaml#/paths/~1api~1v2~1people~1me~1organizations' }
/api/v2/organizations/{organizationId}/members: { $ref: './organizations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1members' }
+ /api/v2/organizations/{organizationId}/profile: { $ref: './organizations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1profile' }
+ /api/v2/organizations/{organizationId}/members/{personId}: { $ref: './organizations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1members~1{personId}' }
+ /api/v2/organizations/{organizationId}/invitations: { $ref: './organizations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1invitations' }
+ /api/v2/organizations/{organizationId}/invitations/{invitationId}: { $ref: './organizations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1invitations~1{invitationId}' }
+ /api/v2/people/me/invitations: { $ref: './organizations.yaml#/paths/~1api~1v2~1people~1me~1invitations' }
+ /api/v2/people/me/invitations/{invitationId}: { $ref: './organizations.yaml#/paths/~1api~1v2~1people~1me~1invitations~1{invitationId}' }
+ /api/v2/people/me/invitations/{invitationId}/accept: { $ref: './organizations.yaml#/paths/~1api~1v2~1people~1me~1invitations~1{invitationId}~1accept' }
+ /api/v2/people/me/invitations/{invitationId}/decline: { $ref: './organizations.yaml#/paths/~1api~1v2~1people~1me~1invitations~1{invitationId}~1decline' }
+ /api/v2/organizations/{organizationId}/teams: { $ref: './teams.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1teams' }
+ /api/v2/organizations/{organizationId}/teams/{teamId}: { $ref: './teams.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1teams~1{teamId}' }
+ /api/v2/organizations/{organizationId}/teams/{teamId}/members: { $ref: './teams.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1teams~1{teamId}~1members' }
+ /api/v2/organizations/{organizationId}/teams/{teamId}/members/{memberId}: { $ref: './teams.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1teams~1{teamId}~1members~1{memberId}' }
/api/v2/organizations/{organizationId}/people/{personId}/approvals: { $ref: './approvals.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1approvals' }
/api/v2/organizations/{organizationId}/people/{personId}/approvals/{approvalId}/decide: { $ref: './approvals.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1approvals~1{approvalId}~1decide' }
/api/v2/organizations/{organizationId}/people/{personId}/questions: { $ref: './approvals.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1questions' }
@@ -424,6 +463,63 @@ components:
description: >-
Desktop and mobile. OAuth 2.1 authorization code with PKCE
(RFC 7636, S256 only); the access token is sent as a bearer token.
+
+
+ Clients. Three public clients are registered: `openbot-desktop-oauth`,
+ `openbot-mobile` and `openbot-cli`. A public client has no secret and
+ must use PKCE with S256. Dynamic client registration is off, so an
+ app uses one of these ids.
+
+
+ Redirect addresses. A client on the person's own computer listens on
+ a loopback address and any port:
+ `http://127.0.0.1:/callback` or
+ `http://[::1]:/callback`. `localhost` is not accepted.
+
+
+ Endpoints. The authorization server's metadata (RFC 8414) is at
+ `/.well-known/oauth-authorization-server/api/auth`. The person is
+ sent to `/api/auth/oauth2/authorize`. The code is exchanged, and a
+ token refreshed, at `/api/auth/oauth2/token`, with a form-encoded
+ body (`application/x-www-form-urlencoded`) that carries `client_id`
+ and no secret: the token and revocation endpoints take no client
+ authentication (`none` in the metadata's
+ `token_endpoint_auth_methods_supported`). A wrong `code_verifier` is
+ answered 400 `invalid_grant`, and the code cannot be used again. A
+ token is revoked (RFC 7009) at `/api/auth/oauth2/revoke`; revoking a
+ token the server does not know, or one already revoked, answers 200.
+
+
+ Tokens. An access token starts `oba_` and lasts one hour. A refresh
+ token starts `obr_`, is issued only when the `offline_access` scope
+ is asked for, and rotates on every use: each refresh answers a new
+ refresh token and ends the one it was given. Access tokens work on
+ /api/v2, and on four addresses outside it that an app's screens need,
+ each with the scope given: `GET /api/me`, who is signed in
+ (people:read); the chat runtime at `/api/copilotkit` and everything
+ under it (conversations:write); a file's download at
+ `GET /api/attachments/{attachmentId}`, the address a sent message
+ keeps (conversations:read); and the relayed realtime socket at
+ `/api/intelligence/client/websocket` (conversations:read). They work
+ nowhere else.
+
+
+ Organization. An access token carries no memory of which
+ organization the person is working in. An address under
+ `/api/v2/organizations/{organizationId}` names it. Where an address
+ names none, such as the list of the person's own organizations, an
+ app sends the header `OpenBot-Organization` with the organization's
+ id. It is checked against the person's membership on every request,
+ and an organization they are not in answers not found. With no
+ header, the app works in the person's own organization.
+
+
+ Consent. The person is asked once for each app, and not again for
+ scopes they already allowed it.
+
+
+ An install for one person on one computer has no sign-in, so it has
+ no OAuth: there is nobody to authorize an app as.
flows:
authorizationCode:
authorizationUrl: /api/auth/oauth2/authorize
@@ -462,7 +558,7 @@ components:
model-catalogue:read: Read the models Bots can run on.
model-choices:read: Read the model the signed-in person chose for each of their conversations.
model-choices:write: Choose the model the signed-in person's conversations answer on.
- apps:read: Read the apps this OpenBot has added, the directory of apps it can add, and how apps are set up here.
+ apps:read: Read the apps the organization has added, the directory of apps it can add, and how apps are set up here.
apps:write: Add, change, refresh and remove apps, when the signed-in person may.
connections:read: Read the signed-in person's connections to apps, and each app's shared account.
connections:write: Connect and disconnect the signed-in person's apps, and an app's shared account when the signed-in person is an administrator.
@@ -514,8 +610,15 @@ components:
scheme: bearer
bearerFormat: OpenBot API key
description: >-
- Automation. An API key acts as the person who created it, inside one
- organization.
+ Automation. An API key acts as the person who created it, in every
+ organization they are a member of, like a personal access token: the
+ address of each request names the organization, and one the person
+ is not in answers not found. A key starts `obk_` and is sent as
+ `Authorization: Bearer ` or in an `x-api-key` header, on /api/v2
+ and on the relayed realtime socket at
+ `/api/intelligence/client/websocket`, where a join token the key made
+ is spent (createConversationJoinToken). A person makes one in the web
+ app, signed in, under Settings, then API keys (createApiKey).
recorderConnection:
type: http
scheme: bearer
@@ -534,8 +637,8 @@ components:
in: path
required: true
description: >-
- The organization, by its id or its slug. Every install has one
- addressed as `default`.
+ The organization, by its id or its slug. One the caller is not a
+ member of answers as one that does not exist, `default` included.
schema:
type: string
minLength: 1
diff --git a/api/openapi/components.yaml b/api/openapi/components.yaml
index 5b0723ff65..5f41314be2 100644
--- a/api/openapi/components.yaml
+++ b/api/openapi/components.yaml
@@ -11,8 +11,12 @@ paths:
operationId: listComponents
summary: List components
description: >-
- Return one page of the components Bots draw in conversations: charts,
- cards and the ones an admin wrote in Playground. An admin sees every
+ Return one page of the components the organization's Bots draw in
+ conversations: charts, cards and the ones an admin wrote in
+ Playground. Each organization has its own: what a component tells the
+ model, whether it is published, which Bots may draw it and which data
+ it may read are decided in one organization and change nothing in
+ another. An admin of the organization sees every
component with its draft, the Bots held back from it and the data it
may read. Anybody else sees the published ones only, and those fields
are null. kind=playground lists only the components written in
@@ -61,14 +65,15 @@ paths:
summary: Announce the components the app can draw
description: >-
Tell OpenBot which components this version of the app can draw. A
- component OpenBot has not seen before is added and published, so
- every Bot can draw it at once. One it already has is left exactly as
- it is: what it tells the model, whether it is published and who may
- use it were decided here. A description nobody here has edited
- follows the one this version of OpenBot ships. In OpenBot Personal a
- component is also given the data it reads. Anybody signed in may
- announce, and the web app does it on every load. The whole list is
- refused if one entry is missing a field.
+ component the organization has not seen before is added and
+ published, so every one of its Bots can draw it at once. One it
+ already has is left exactly as it is: what it tells the model,
+ whether it is published and who may use it were decided here. A
+ description nobody here has edited follows the one this version of
+ OpenBot ships. In OpenBot Personal a component is also given the data
+ it reads. Anybody signed in may announce, and the web app does it on
+ every load. The whole list is refused if one entry is missing a field
+ or has a name that starts with @.
security:
- webSession: []
- appOAuth: [components:write]
@@ -95,7 +100,7 @@ paths:
description: Show how many actions each Bot took recently.
responses:
'200':
- description: The components this announcement added. Empty when OpenBot had them all.
+ description: The components this announcement added. Empty when the organization had them all.
headers:
Cache-Control:
$ref: './common.yaml#/components/headers/PrivateNoStore'
@@ -990,7 +995,7 @@ components:
type: string
minLength: 1
pattern: \S
- description: The tool name a Bot draws it by. Trimmed.
+ description: The tool name a Bot draws it by. Trimmed. It can't start with @.
title:
type: string
minLength: 1
@@ -1190,13 +1195,24 @@ components:
A field is missing or blank once trimmed, holds text that can't be
kept, or doesn't fit this kind of component: a title or source for
one that comes with OpenBot, a Playground name that isn't custom_ and
- lower-case letters, numbers and underscores, or a data function this
- OpenBot doesn't ship.
+ lower-case letters, numbers and underscores, an announced name that
+ starts with @, or a data function this OpenBot doesn't ship.
content:
application/problem+json:
schema:
$ref: './common.yaml#/components/schemas/Problem'
examples:
+ nameStartsWithAt:
+ value:
+ type: https://open.bot/errors/validation-error
+ title: Request validation failed.
+ status: 400
+ detail: Component at index 0 has a name that starts with @, which a component's name can't.
+ code: VALIDATION_ERROR
+ category: validation
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
announcement:
value:
type: https://open.bot/errors/validation-error
diff --git a/api/openapi/computers.yaml b/api/openapi/computers.yaml
index 7789bb8857..067d2d6cb1 100644
--- a/api/openapi/computers.yaml
+++ b/api/openapi/computers.yaml
@@ -11,10 +11,12 @@ paths:
operationId: listComputers
summary: List the organization's computers
description: >-
- Return one page of the computers Bots run on: each person's, and each
- isolated Bot's. Where every person's Bots share one computer, each
- entry is one person's seat on one Bot there. Ordered by whose computer
- it is, then by Bot. Only an administrator may read them. A missing
+ Return one page of the computers the organization's Bots run on: each
+ person's, and each isolated Bot's. Where every person's Bots share one
+ computer, each entry is one person's seat on one Bot there. A computer
+ another organization's Bots run on is never listed. Ordered by whose
+ computer it is, then by Bot. Only an administrator of the organization
+ may read them. A missing
cursor starts at the first page and nextCursor null ends the list.
security:
- webSession: []
@@ -61,8 +63,9 @@ paths:
Stop one computer from the list now, and record it on the audit trail.
Its files and sign-ins stay, and it starts again when a Bot next needs
it. The computer is named by whose it is, person: or bot:;
- botId names one Bot's seat on a shared computer. Only an administrator
- may do this.
+ botId names one Bot's seat on a shared computer. A computer that is
+ not one of the organization's is not found. Only an administrator of
+ the organization may do this.
security:
- webSession: []
- appOAuth: [computers:write]
@@ -99,7 +102,7 @@ paths:
'403':
$ref: './common.yaml#/components/responses/AdminOnly'
'404':
- $ref: './common.yaml#/components/responses/OrganizationNotFound'
+ $ref: '#/components/responses/OrganizationComputerNotFound'
'409':
$ref: './common.yaml#/components/responses/IdempotencyConflict'
'500':
@@ -119,7 +122,8 @@ paths:
Delete one computer's browser profile, and every sign-in with it, and
record it on the audit trail. The computer is named by whose it is,
person: or bot:; botId names one Bot's seat on a shared
- computer. Only an administrator may do this.
+ computer. A computer that is not one of the organization's is not
+ found. Only an administrator of the organization may do this.
security:
- webSession: []
- appOAuth: [computers:write]
@@ -156,7 +160,7 @@ paths:
'403':
$ref: './common.yaml#/components/responses/AdminOnly'
'404':
- $ref: './common.yaml#/components/responses/OrganizationNotFound'
+ $ref: '#/components/responses/OrganizationComputerNotFound'
'409':
$ref: './common.yaml#/components/responses/IdempotencyConflict'
'500':
@@ -176,7 +180,8 @@ paths:
Move one computer onto the image this OpenBot now runs, and record it
on the audit trail. Files and sign-ins stay; a running computer
restarts. The computer is named by whose it is, person: or
- bot:. Only an administrator may do this.
+ bot:. A computer that is not one of the organization's is not
+ found. Only an administrator of the organization may do this.
security:
- webSession: []
- appOAuth: [computers:write]
@@ -213,7 +218,7 @@ paths:
'403':
$ref: './common.yaml#/components/responses/AdminOnly'
'404':
- $ref: './common.yaml#/components/responses/OrganizationNotFound'
+ $ref: '#/components/responses/OrganizationComputerNotFound'
'409':
$ref: './common.yaml#/components/responses/IdempotencyConflict'
'500':
@@ -2150,7 +2155,8 @@ components:
Computer:
type: object
description: >-
- One computer as an administrator sees it: a person's, or an isolated
+ One of the organization's computers as its administrator sees it: a
+ person's, or an isolated
Bot's. Where every person's Bots share one computer, one person's
seat on one Bot there.
required: [id, computer, kind, running, startedAt]
@@ -2338,6 +2344,37 @@ components:
retryable: false
requestId: req_example
traceId: trace_example
+ OrganizationComputerNotFound:
+ description: >-
+ The computer named is not one of the organization's Bots' computers,
+ or the organization does not exist.
+ content:
+ application/problem+json:
+ schema:
+ $ref: './common.yaml#/components/schemas/Problem'
+ examples:
+ computer:
+ value:
+ type: https://open.bot/errors/bot-not-found
+ title: Bot not found.
+ status: 404
+ detail: Couldn't find that computer.
+ code: BOT_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ organization:
+ value:
+ type: https://open.bot/errors/organization-not-found
+ title: Organization not found.
+ status: 404
+ detail: Couldn't find that organization.
+ code: ORGANIZATION_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
ComputerBotNotFound:
description: >-
The Bot does not exist or is not the caller's to use, a file or a
diff --git a/api/openapi/connections.yaml b/api/openapi/connections.yaml
index 8225180f74..b4f1576315 100644
--- a/api/openapi/connections.yaml
+++ b/api/openapi/connections.yaml
@@ -1,5 +1,5 @@
# Connections: a person's connections to apps, the accounts they connected at each, and the consent
-# for one action; and an app's one shared account, which an administrator connects for everybody.
+# for one action; and an app's one shared account, which an administrator connects for the organization.
#
# One area of OpenBot's REST API. `bun run api:bundle` joins every area with common.yaml into
# api/openapi.yaml, the file every client and check reads. See api/README.md.
@@ -659,9 +659,11 @@ paths:
operationId: getSharedConnection
summary: Read an app's shared account
description: >-
- Return the one account an app in Shared mode acts as for everybody:
- whether it is connected, who connected it, and the app's own name
- for the account. Anybody signed in may read it. Not found when the
+ Return the one account an app in Shared mode acts as for everybody in
+ the organization: whether it is connected, who connected it, and the
+ app's own name for the account. Each organization connects its own,
+ and one organization's shared account is never used in another. Any
+ member of the organization may read it. Not found when the
app is connected by each person instead, as getConnection reads.
x-openbot-singleton: true
security:
@@ -703,13 +705,15 @@ paths:
summary: Start connecting an app's shared account
description: >-
Start connecting the one account an app in Shared mode acts as for
- everybody, and say what happens next, as connectApp does: consent
+ everybody in the organization, and say what happens next, as
+ connectApp does: consent
answers the address of the app's sign-in page, form answers the boxes
to fill in, connected means it is connected already. The person comes
back to the app's page, where confirmSharedConnection checks the
result. Where an app connects once, a shared account already connected
- is a conflict: disconnect it first. Only an administrator may connect
- it. The address and the values are never logged.
+ is a conflict: disconnect it first. Only an administrator of the
+ organization may connect it. The address and the values are never
+ logged.
security:
- webSession: []
- appOAuth: [connections:write]
diff --git a/api/openapi/conversations.yaml b/api/openapi/conversations.yaml
index a65852d44a..42247c3c9e 100644
--- a/api/openapi/conversations.yaml
+++ b/api/openapi/conversations.yaml
@@ -74,7 +74,11 @@ paths:
once and for about half a minute, so ask for a new one for every
connection, and again to reconnect. Only a person in the conversation
may have one, and it opens the thread they see there and no other. A
- conversation no Bot has run in yet has nothing to join.
+ conversation no Bot has run in yet has nothing to join (409). Where
+ realtime.clientUrl is on this server, open it with the same
+ credential that made the token: the session, an app's access token,
+ or an API key, as Authorization: Bearer or x-api-key. So a script
+ that holds only an API key can watch a conversation live.
security:
- webSession: []
- appOAuth: [conversations:read]
@@ -1687,11 +1691,18 @@ components:
minLength: 1
description: >-
The socket's address, without the /websocket it ends in or its
- query. A ws or wss address, or a path on this server.
+ query. A ws or wss address, or a path on this server, which is
+ resolved against the address the API was called at. Where it
+ is on this server, the socket is opened with the credential
+ that made the token (see createConversationJoinToken).
topic:
type: string
pattern: ^thread:.+$
- description: The topic to join on the socket, thread:{threadId}.
+ description: >-
+ The topic to join on the socket, as the realtime gateway knows
+ the thread. Use it as given: outside the organization default
+ it does not name threadId, so a topic made from threadId joins
+ nothing.
Conversation:
type: object
description: A conversation between the caller and one or more Bots.
@@ -2240,7 +2251,9 @@ components:
properties:
id:
type: string
- description: The caller's own id for the message, so a retry is the same message.
+ description: The caller's own id for the message, any string, so a retry in the
+ same conversation is the same message. The conversation's messages
+ list it under this id.
minLength: 1
maxLength: 160
text:
@@ -2313,6 +2326,12 @@ components:
threadId:
type: string
description: The new thread's id.
+ liveThreadId:
+ type: string
+ description: The id that live updates about this thread carry. Compare
+ an incoming update with this one, and use threadId everywhere else.
+ It is threadId itself in the organization default. Left out by a
+ server that names threads one way only, where it is threadId.
ConversationThreadStatus:
type: object
required:
@@ -2324,6 +2343,12 @@ components:
known:
type: boolean
description: Whether the thread still holds the caller's conversation.
+ liveThreadId:
+ type: string
+ description: The id that live updates about this thread carry. Compare
+ an incoming update with this one, and use threadId everywhere else.
+ It is threadId itself in the organization default. Left out by a
+ server that names threads one way only, where it is threadId.
TaskStatus:
type: string
enum:
@@ -3068,10 +3093,10 @@ components:
value: {"transport": "webrtc"}
ConversationThreadExample:
summary: "A new thread id."
- value: {"threadId": "6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a"}
+ value: {"threadId": "6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a", "liveThreadId": "2b503bf7-514a-8c4e-b132-3ca9b729ffeb"}
ConversationThreadStatusExample:
summary: "A thread that is still there."
- value: {"threadId": "6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a", "known": true}
+ value: {"threadId": "6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a", "known": true, "liveThreadId": "2b503bf7-514a-8c4e-b132-3ca9b729ffeb"}
TaskPageExample:
summary: "One task, ready to read."
value: {"tasks": [{"id": "7c2d6b1f-6f10-4a53-9d51-5f0d6c0e2f1a", "botId": "general-assistant", "conversationId": "5f0d6c0e-2f1a-4a53-9d51-6f3d6b1f6f10", "threadId": "6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a", "title": "Reply to Sam about the spec", "why": "Sam asked for the spec by Friday.", "origin": "check_in", "suggestionId": "0b1c6f0e-7f0e-4c1e-9d55-2f4a8c1b6e21", "sourceApp": "Gmail", "sourceLink": null, "originConversationId": null, "status": "ready_for_review", "failure": null, "failedAt": null, "stoppedAt": null, "next": "Read the draft and send it.", "workingSince": null, "lastActivityAt": "2026-11-14T09:05:00.000Z", "resolvedAt": null, "createdAt": "2026-11-14T09:00:00.000Z", "updatedAt": "2026-11-14T09:05:00.000Z"}], "nextCursor": null}
diff --git a/api/openapi/learning.yaml b/api/openapi/learning.yaml
index 112758d1e6..2ce6b66580 100644
--- a/api/openapi/learning.yaml
+++ b/api/openapi/learning.yaml
@@ -4,7 +4,10 @@
# api/openapi.yaml, the file every client and check reads. See api/README.md.
#
# CopilotKit Intelligence learns skills from conversations and recordings, in Learning spaces
-# (containers) inside the organization's Intelligence project. What it proposes, the evidence behind
+# (containers) that belong to one organization. Every organization has its own spaces, and each
+# person has their own space in each organization they belong to: what is learned in one
+# organization never reaches a Bot in another, the same person's Bots included, and "every Bot"
+# below always means every Bot in the organization. What it proposes, the evidence behind
# each proposal, approving and rejecting one, and its runs live in Intelligence: OpenBot reads and
# changes them for a person, after checking which spaces that person may reach, and answers in the
# shapes below. Beside them is what OpenBot keeps: which space each Bot learns into, who reviews
@@ -14,6 +17,7 @@
# The organization's spaces (the one every Bot learns into, and each Bot's own) are an
# administrator's, under settings/learning, picked with botId. A person's own spaces are under
# people/{personId}, picked with containerId; an administrator may read and review them too.
+# An administrator here is an administrator of the organization in the address, and of no other.
paths:
/api/v2/organizations/{organizationId}/settings/learning:
parameters:
@@ -1800,6 +1804,19 @@ components:
oneOf:
- $ref: '#/components/schemas/LearningAutomatic'
- type: 'null'
+ organizationSpaceId:
+ description: >-
+ The space OpenBot keeps for this organization alone, which its
+ Bots learn into unless an administrator chooses another. Another
+ space of the organization's is named after it: this id, a hyphen,
+ then a name of the administrator's choosing. The id says nothing
+ a person can read, so a screen names the space by the
+ organization and never shows it. Null, or absent, where OpenBot
+ keeps no space for the organization alone and its default is
+ whichever space is assigned or chosen.
+ oneOf:
+ - $ref: '#/components/schemas/LearningSpaceId'
+ - type: 'null'
LearningAutomaticResult:
type: object
required: [automatic]
@@ -2040,8 +2057,9 @@ components:
enum: [closed, open, choose]
description: >-
Who else's Bots use the skills learned in a person's own space.
- closed: only their own Bots. open: every Bot. choose: every Bot, for
- the skills they open one by one.
+ closed: only their own Bots. open: every Bot in the organization.
+ choose: every Bot in the organization, for the skills they open one
+ by one. Never a Bot in another organization.
PersonalLearnedSkill:
type: object
required: [name, description, open, approvedBy, sharing]
diff --git a/api/openapi/memory.yaml b/api/openapi/memory.yaml
index 927ed23fac..1610c1965e 100644
--- a/api/openapi/memory.yaml
+++ b/api/openapi/memory.yaml
@@ -9,6 +9,10 @@
# does the recall, and the memories Intelligence holds for the person that OpenBot formed no record
# of are listed here too. Without it, OpenBot's record is the whole store. A single-person OpenBot
# keeps no memory: every operation here answers not found there.
+#
+# A person's memory is kept per organization. What their Bots remember in one organization is never
+# listed or recalled in another they belong to, and a memory named from another organization is
+# answered as not found.
paths:
/api/v2/organizations/{organizationId}/people/{personId}/memories:
parameters:
@@ -19,8 +23,9 @@ paths:
operationId: listMemories
summary: List a person's memories
description: >-
- Return one page of what a person's Bots remember about them, most
- recently changed first: the ones they wrote, the ones their Bots
+ Return one page of what a person's Bots remember about them in this
+ organization, and in no other they belong to, most recently changed
+ first: the ones they wrote, the ones their Bots
formed and are waiting for their review, the ones read in from their
sources, and the ones the backend holds for them that OpenBot formed
no record of, after OpenBot's own. Paused memories are included;
diff --git a/api/openapi/model-connections.yaml b/api/openapi/model-connections.yaml
index 237de7bcbc..e42d9df16a 100644
--- a/api/openapi/model-connections.yaml
+++ b/api/openapi/model-connections.yaml
@@ -11,10 +11,13 @@ paths:
operationId: listCredentials
summary: List the credentials in the vault
description: >-
- Return one page of the credentials the vault keeps, live and revoked,
- oldest first. A credential says what it is for and whether it is live,
- and never holds its secret: nothing in the API reads a secret back out.
- Only an administrator may list them. A missing cursor starts at the
+ Return one page of the credentials the organization's vault keeps,
+ live and revoked, oldest first. Each organization has its own vault,
+ and another organization's credentials are never listed. A credential
+ says what it is for and whether it is live, and never holds its
+ secret: nothing in the API reads a secret back out. Only an
+ administrator of the organization may list them. A missing cursor
+ starts at the
first page and nextCursor null ends the list.
security:
- webSession: []
@@ -55,13 +58,14 @@ paths:
operationId: createCredential
summary: Add a credential to the vault
description: >-
- Encrypt a secret and keep it in the vault under one key: a kind, a
+ Encrypt a secret and keep it in the organization's vault under one
+ key: a kind, a
provider and a key id. A key holds one live credential, so adding one
for a key that already has one replaces it, and the one it replaces is
revoked in the same write. A model key sent without a key id is filed
under the name OpenBot's own Bots read (getModelKey). The secret is
write-only: no answer includes it, now or later. Recorded on the audit
- trail. Only an administrator may add one.
+ trail. Only an administrator of the organization may add one.
security:
- webSession: []
- appOAuth: [credentials:write]
@@ -120,8 +124,9 @@ paths:
description: >-
Stop a live credential being used, and keep its record. Nothing reads
a revoked credential again. Recorded on the audit trail. Only an
- administrator may revoke one. One that does not exist, or is revoked
- already, is not found.
+ administrator of the organization may revoke one. One that does not
+ exist, is in another organization's vault, or is revoked already, is
+ not found.
security:
- webSession: []
- appOAuth: [credentials:write]
@@ -166,9 +171,9 @@ paths:
summary: Read where the Bots find their model key
description: >-
Return the provider OpenBot's own Bots run on, the key id their model
- key is filed under in the vault, and whether a live key is kept there.
- Never the key. A model key added without a key id is filed here. Only
- an administrator may read it.
+ key is filed under in the organization's vault, and whether a live key
+ is kept there. Never the key. A model key added without a key id is
+ filed here. Only an administrator of the organization may read it.
x-openbot-singleton: true
security:
- webSession: []
@@ -394,7 +399,8 @@ components:
Credential:
type: object
description: >-
- A credential in the vault as the API shows it: what it is for and
+ A credential in the organization's vault as the API shows it: what it
+ is for and
whether it is live. Never its secret, which only ever goes in.
required: [id, kind, provider, keyId, metadata, createdAt, revokedAt]
properties:
diff --git a/api/openapi/notifications.yaml b/api/openapi/notifications.yaml
index 47961a5b3b..2c82710924 100644
--- a/api/openapi/notifications.yaml
+++ b/api/openapi/notifications.yaml
@@ -160,7 +160,11 @@ paths:
Return one page of the places outside OpenBot a person continues
their conversations with Bots: a Slack or Microsoft Teams chat, or a
phone number for text messages, each tied to one conversation with
- one Bot. The first connected first. Only the person themselves may
+ one Bot. A Slack account, a Teams account or a phone number is
+ connected in one organization at a time: connecting one that is
+ connected in another organization answers 400 until it is
+ disconnected there. The first connected first. Only the person
+ themselves may
list them; there is no administrator view. A missing cursor starts at
the first page and nextCursor null ends the list.
security:
@@ -1191,13 +1195,25 @@ components:
description: >-
The request doesn't match the API, the conversation isn't the
person's or the Bot isn't in it, a phone's verification expired, was
- used already or its code was wrong, or the phone is connected to
- another person.
+ used already or its code was wrong, the phone is connected to
+ another person, or the Slack account, Teams account or phone is
+ connected in another organization.
content:
application/problem+json:
schema:
$ref: './common.yaml#/components/schemas/Problem'
examples:
+ connectedInAnotherOrganization:
+ value:
+ type: https://open.bot/errors/validation-error
+ title: Request validation failed.
+ status: 400
+ detail: That account is already connected to OpenBot in another organization. Disconnect it there, then connect it here.
+ code: VALIDATION_ERROR
+ category: validation
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
notTheirs:
value:
type: https://open.bot/errors/validation-error
diff --git a/api/openapi/organizations.yaml b/api/openapi/organizations.yaml
index 15941070d3..7b2078f78c 100644
--- a/api/openapi/organizations.yaml
+++ b/api/openapi/organizations.yaml
@@ -12,11 +12,19 @@ paths:
Return one page of the organizations the caller is a member of, the
one they joined first at the top, each with the caller's role in it.
active marks the one the caller's session is working in, which is
- where every address outside /api/v2 reads and writes; a request
- signed in with an API key or an app's token has no session, so none
- is active. To work in another one, set it as the session's active
- organization (POST /api/auth/organization/set-active). A missing
- cursor starts at the first page and nextCursor null ends the list.
+ where every address outside /api/v2 reads and writes. A request
+ signed in with an API key has no session, so none is active. An
+ app's token has no session either: for it, active marks the
+ organization its OpenBot-Organization header names, or the caller's
+ own when it sends none. The header is checked against the caller's
+ membership, as on every address that names no organization, so one
+ they are not in answers not found. A session and an API key ignore
+ it. To work in another one, set it as the
+ session's active organization
+ (POST /api/auth/organization/set-active). Made with an app's token,
+ that call checks that the caller is a member, stores nothing and
+ answers the organization. A missing cursor starts at the first page
+ and nextCursor null ends the list.
security:
- webSession: []
- appOAuth: [organizations:read]
@@ -24,6 +32,19 @@ paths:
parameters:
- $ref: './common.yaml#/components/parameters/Limit'
- $ref: './common.yaml#/components/parameters/Cursor'
+ - name: OpenBot-Organization
+ in: header
+ required: false
+ description: >-
+ For a request signed in with an app's token: the organization it
+ works in, by id or slug, which the list marks active. Without it
+ the caller's own is active. One the caller is not a member of
+ answers not found, and one that is not a single id or slug 400.
+ Ignored for a session and an API key.
+ schema:
+ type: string
+ minLength: 1
+ maxLength: 200
responses:
'200':
description: One page of organizations.
@@ -43,6 +64,8 @@ paths:
$ref: './common.yaml#/components/responses/Unauthenticated'
'403':
$ref: './common.yaml#/components/responses/Forbidden'
+ '404':
+ $ref: './common.yaml#/components/responses/OrganizationNotFound'
'500':
$ref: './common.yaml#/components/responses/ServerError'
default:
@@ -52,11 +75,13 @@ paths:
operationId: createOrganization
summary: Create an organization
description: >-
- Create an organization with the caller as its owner. It starts with no
- Bots and no conversations. Who may create one is the deployment's
- choice: its admins (the admins of `default`) unless it lets anybody
- signed in. Without a slug, one is made from the name. The caller's
- session keeps working where it was. A repeated request with the same
+ Create an organization with the caller as its owner. It starts with
+ what a fresh install starts with, its starter Bots included, and no
+ conversations. Everybody already has an organization of
+ their own, made when they first signed in; this is for making another,
+ which anybody signed in may do where OpenBot keeps more than one.
+ Without a slug, one is made from the name. The caller's session keeps
+ working where it was. A repeated request with the same
Idempotency-Key and body returns the first result.
security:
- webSession: []
@@ -93,7 +118,7 @@ paths:
'401':
$ref: './common.yaml#/components/responses/Unauthenticated'
'403':
- $ref: './common.yaml#/components/responses/AdminOnly'
+ $ref: './common.yaml#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/OrganizationConflict'
'500':
@@ -102,6 +127,63 @@ paths:
$ref: '#/components/responses/OrganizationNotCreated'
default:
$ref: './common.yaml#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/profile:
+ parameters:
+ - $ref: './common.yaml#/components/parameters/OrganizationId'
+ patch:
+ tags: [Organizations]
+ operationId: updateOrganization
+ summary: Rename an organization
+ description: >-
+ Give the organization a new name. Its id and its slug stay as they
+ are, so every address that names it keeps working. An organization
+ OpenBot named after its person stops following what that person is
+ called once it has been renamed. Only an owner or an admin of this
+ organization can. A repeated request with the same Idempotency-Key
+ and body returns the first result.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:write]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateOrganizationRequest'
+ examples:
+ renamed:
+ value:
+ name: Acme Research Lab
+ responses:
+ '200':
+ description: The organization, renamed.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OrganizationResponse'
+ examples:
+ renamed:
+ $ref: '#/components/examples/RenamedOrganization'
+ '400':
+ $ref: '#/components/responses/InvalidOrganization'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/AdminOnly'
+ '404':
+ $ref: './common.yaml#/components/responses/OrganizationNotFound'
+ '409':
+ $ref: './common.yaml#/components/responses/IdempotencyConflict'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
/api/v2/organizations/{organizationId}/members:
parameters:
- $ref: './common.yaml#/components/parameters/OrganizationId'
@@ -145,15 +227,164 @@ paths:
$ref: './common.yaml#/components/responses/ServerError'
default:
$ref: './common.yaml#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/members/{personId}:
+ parameters:
+ - $ref: './common.yaml#/components/parameters/OrganizationId'
+ - $ref: './common.yaml#/components/parameters/PersonId'
+ patch:
+ tags: [Organizations]
+ operationId: updateOrganizationMember
+ summary: Change a member's role
+ description: >-
+ Give a member of the organization another role. An owner or an admin
+ changes anybody between admin and member. Only an owner makes
+ somebody an owner, or changes an owner's role, their own included,
+ and the organization always keeps an owner: the last one cannot step
+ down. A person's own organization keeps exactly its one owner. The
+ members list says which roles the caller may give each member, as
+ assignableRoles. A repeated request with the same Idempotency-Key
+ and body returns the first result.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:write]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateOrganizationMemberRequest'
+ examples:
+ owner:
+ value:
+ role: owner
+ responses:
+ '200':
+ description: The member, with their new role.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OrganizationMemberResponse'
+ examples:
+ owner:
+ $ref: '#/components/examples/PromotedOrganizationMember'
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/AdminOnly'
+ '404':
+ $ref: './common.yaml#/components/responses/PersonNotFound'
+ '409':
+ $ref: '#/components/responses/OwnerStays'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ delete:
+ tags: [Organizations]
+ operationId: removeOrganizationMember
+ summary: Remove a member, or leave an organization
+ description: >-
+ End somebody's membership of the organization. An owner or an admin
+ of it can remove anybody whose membership can end, and any such
+ member can leave by naming themselves or `me`. The owner stays, so
+ nobody leaves their own organization, and so does somebody this
+ OpenBot's settings keep as an admin of it. The person keeps their account and their
+ other organizations, and what they made here stays here. Removing
+ somebody who is not a member answers the same as removing one.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:write]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/IdempotencyKey'
+ responses:
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '204':
+ description: They are not a member.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/AdminOnly'
+ '404':
+ $ref: './common.yaml#/components/responses/OrganizationNotFound'
+ '409':
+ $ref: '#/components/responses/OwnerStays'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/invitations:
+ parameters:
+ - $ref: './common.yaml#/components/parameters/OrganizationId'
+ get:
+ tags: [Organizations]
+ operationId: listOrganizationInvitations
+ summary: List the invitations an organization has sent
+ description: >-
+ Return one page of the organization's invitations that have not been
+ accepted or canceled, the newest first: the ones still waiting, the
+ ones that expired and the ones that were declined. Only an owner or an
+ admin of this organization can read it. A missing cursor starts at the
+ first page and nextCursor null ends the list.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:read]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/Limit'
+ - $ref: './common.yaml#/components/parameters/Cursor'
+ responses:
+ '200':
+ description: One page of invitations.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OrganizationInvitationPage'
+ examples:
+ lastPage:
+ $ref: '#/components/examples/OrganizationInvitationPageLast'
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/AdminOnly'
+ '404':
+ $ref: './common.yaml#/components/responses/OrganizationNotFound'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
post:
tags: [Organizations]
- operationId: addOrganizationMember
- summary: Add a person to an organization
+ operationId: createOrganizationInvitation
+ summary: Invite somebody to an organization
description: >-
- Make somebody who already has an account here a member of the
- organization, by their email address, with a role. Only an owner or
- an admin of this organization can. A repeated request with the same
- Idempotency-Key and body returns the first result.
+ Invite the person with this email address to join the organization
+ with a role. They need no account yet: the invitation waits for
+ whoever signs in with that address, and they see it in OpenBot then.
+ Where OpenBot can send email, it also emails them; delivery says
+ which happened, so the inviter knows whether to pass the link on
+ themselves. The invitation lasts seven days. Inviting an address
+ again after its invitation expired or was declined starts a new one.
+ Only an owner or an admin of this organization can. A repeated
+ request with the same Idempotency-Key and body returns the first
+ result.
security:
- webSession: []
- appOAuth: [organizations:write]
@@ -165,7 +396,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/AddOrganizationMemberRequest'
+ $ref: '#/components/schemas/CreateOrganizationInvitationRequest'
examples:
member:
value:
@@ -173,45 +404,260 @@ paths:
role: member
responses:
'201':
- description: The person is now a member.
+ description: The invitation was made.
headers:
Cache-Control:
$ref: './common.yaml#/components/headers/PrivateNoStore'
Location:
- description: The organization's members.
+ description: The organization's invitations.
schema:
type: string
- example: /api/v2/organizations/Jq3xT9mLw2Vb8RnC5sYd0fKe/members
+ example: /api/v2/organizations/Jq3xT9mLw2Vb8RnC5sYd0fKe/invitations
content:
application/json:
schema:
- $ref: '#/components/schemas/OrganizationMemberResponse'
+ $ref: '#/components/schemas/OrganizationInvitationResponse'
examples:
- added:
- $ref: '#/components/examples/AddedOrganizationMember'
+ invited:
+ $ref: '#/components/examples/CreatedOrganizationInvitation'
'400':
- $ref: '#/components/responses/InvalidOrganizationMember'
+ $ref: '#/components/responses/InvalidOrganizationInvitation'
'401':
$ref: './common.yaml#/components/responses/Unauthenticated'
'403':
$ref: './common.yaml#/components/responses/AdminOnly'
'404':
- $ref: '#/components/responses/OrganizationOrPersonNotFound'
+ $ref: './common.yaml#/components/responses/OrganizationNotFound'
+ '409':
+ $ref: '#/components/responses/OrganizationInvitationConflict'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/invitations/{invitationId}:
+ parameters:
+ - $ref: './common.yaml#/components/parameters/OrganizationId'
+ - $ref: '#/components/parameters/InvitationId'
+ delete:
+ tags: [Organizations]
+ operationId: cancelOrganizationInvitation
+ summary: Cancel an invitation
+ description: >-
+ Take back an invitation the organization sent, whatever state it is
+ in. It leaves the organization's list and the invited person's. Only
+ an owner or an admin of this organization can.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:write]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/IdempotencyKey'
+ responses:
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '204':
+ description: The invitation is canceled.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/OrganizationOrInvitationNotFound'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ /api/v2/people/me/invitations:
+ get:
+ tags: [Organizations]
+ operationId: listInvitations
+ summary: List the caller's invitations
+ description: >-
+ Return one page of the invitations sent to the caller's email address
+ that they have not answered, the newest first, each with the
+ organization and who invited them. One that ran out of time is listed
+ as expired until it is canceled or replaced. A missing cursor starts
+ at the first page and nextCursor null ends the list.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:read]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/Limit'
+ - $ref: './common.yaml#/components/parameters/Cursor'
+ responses:
+ '200':
+ description: One page of invitations.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/InvitationPage'
+ examples:
+ lastPage:
+ $ref: '#/components/examples/InvitationPageLast'
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/Forbidden'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ /api/v2/people/me/invitations/{invitationId}:
+ parameters:
+ - $ref: '#/components/parameters/InvitationId'
+ get:
+ tags: [Organizations]
+ operationId: getInvitation
+ summary: Read one of the caller's invitations
+ description: >-
+ Return an invitation sent to the caller's email address, in whatever
+ state it is in, so the page a link opens can say what happened to it.
+ An invitation sent to another address answers as one that does not
+ exist.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:read]
+ - apiKey: []
+ responses:
+ '200':
+ description: The invitation.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/InvitationResponse'
+ examples:
+ waiting:
+ $ref: '#/components/examples/WaitingInvitation'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/Forbidden'
+ '404':
+ $ref: '#/components/responses/InvitationNotFound'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ /api/v2/people/me/invitations/{invitationId}/accept:
+ parameters:
+ - $ref: '#/components/parameters/InvitationId'
+ post:
+ tags: [Organizations]
+ operationId: acceptInvitation
+ summary: Accept an invitation
+ description: >-
+ Join the organization the invitation is for, with the role it offers.
+ The caller's session keeps working where it was; switch to the new
+ organization to work in it. An invitation that expired, was canceled
+ or was already answered is refused in words. A repeated request with
+ the same Idempotency-Key returns the first result.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:write]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/IdempotencyKey'
+ responses:
+ '200':
+ description: The caller is now a member of the organization.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OrganizationResponse'
+ examples:
+ joined:
+ $ref: '#/components/examples/JoinedOrganization'
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/Forbidden'
+ '404':
+ $ref: '#/components/responses/InvitationNotFound'
'409':
- $ref: '#/components/responses/OrganizationMemberConflict'
+ $ref: '#/components/responses/InvitationNotWaiting'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ /api/v2/people/me/invitations/{invitationId}/decline:
+ parameters:
+ - $ref: '#/components/parameters/InvitationId'
+ post:
+ tags: [Organizations]
+ operationId: declineInvitation
+ summary: Decline an invitation
+ description: >-
+ Turn the invitation down. It leaves the caller's list, and the
+ organization sees that it was declined. A repeated request with the
+ same Idempotency-Key returns the first result.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:write]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/IdempotencyKey'
+ responses:
+ '204':
+ description: The invitation is declined.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/Forbidden'
+ '404':
+ $ref: '#/components/responses/InvitationNotFound'
+ '409':
+ $ref: '#/components/responses/InvitationNotWaiting'
'500':
$ref: './common.yaml#/components/responses/ServerError'
default:
$ref: './common.yaml#/components/responses/UnexpectedError'
components:
+ parameters:
+ InvitationId:
+ name: invitationId
+ in: path
+ required: true
+ description: The invitation's id. Opaque.
+ schema:
+ type: string
+ minLength: 1
+ maxLength: 128
+ pattern: ^[A-Za-z0-9_-]+$
schemas:
Organization:
type: object
description: >-
One organization, as one of its members sees it. role and active are
the server's verdicts about the caller.
- required: [id, slug, name, role, active]
+ required: [id, slug, name, role, active, personal]
properties:
+ personal:
+ type: boolean
+ description: >-
+ Whether this is the caller's own organization: the one OpenBot
+ made for them when they first signed in.
id:
type: string
description: The organization's id. Opaque.
@@ -226,8 +672,10 @@ components:
active:
type: boolean
description: >-
- Whether the caller's session is working in this one. Always false
- for a request with no session.
+ Whether the caller is working in this one: the organization their
+ session works in, or for an app's token the one its
+ OpenBot-Organization header names, else the caller's own. Always
+ false for a request made with an API key.
OrganizationPage:
type: object
required: [organizations, canCreate, nextCursor]
@@ -240,9 +688,9 @@ components:
canCreate:
type: boolean
description: >-
- Whether the caller may create an organization: the server's
- verdict, true for the deployment's admins and for anybody signed
- in when the deployment lets them. The same on every page.
+ Whether the caller may create another organization: the server's
+ verdict, true for anybody signed in where OpenBot keeps more than
+ one organization. The same on every page.
nextCursor:
type: [string, 'null']
maxLength: 4096
@@ -278,8 +726,24 @@ components:
OrganizationMember:
type: object
description: One member of an organization.
- required: [id, email, name, image, role, joinedAt]
+ required: [id, email, name, image, role, joinedAt, removable, assignableRoles]
properties:
+ removable:
+ type: boolean
+ description: >-
+ Whether this membership can end: an admin can remove them and
+ they can leave. The server's verdict. False for the
+ organization's last owner, who stays in it, for the owner of
+ their own organization, and for somebody this OpenBot's settings
+ keep as an admin of the organization.
+ assignableRoles:
+ type: array
+ description: >-
+ The roles the caller may give this member, their current one left
+ out. The server's verdict. Empty when the caller may not change
+ this member's role.
+ items:
+ $ref: './common.yaml#/components/schemas/PersonRole'
id:
type: string
description: The person's id.
@@ -320,7 +784,97 @@ components:
properties:
member:
$ref: '#/components/schemas/OrganizationMember'
- AddOrganizationMemberRequest:
+ UpdateOrganizationMemberRequest:
+ type: object
+ additionalProperties: false
+ required: [role]
+ properties:
+ role:
+ $ref: './common.yaml#/components/schemas/PersonRole'
+ UpdateOrganizationRequest:
+ type: object
+ additionalProperties: false
+ required: [name]
+ properties:
+ name:
+ type: string
+ minLength: 1
+ maxLength: 100
+ pattern: ^[^\x00]*\S[^\x00]*$
+ description: What people call it.
+ InvitationSender:
+ type: object
+ description: Who sent an invitation.
+ required: [name, email]
+ properties:
+ name:
+ type: [string, 'null']
+ description: What OpenBot calls them. Null until they choose.
+ email:
+ type: string
+ description: Their address.
+ OrganizationInvitation:
+ type: object
+ description: >-
+ An invitation an organization sent, as its admins see it. status is
+ the server's verdict.
+ required: [id, email, role, status, invitedBy, createdAt, expiresAt]
+ properties:
+ id:
+ type: string
+ description: The invitation's id. Opaque.
+ email:
+ type: string
+ description: The address it was sent to.
+ role:
+ $ref: './common.yaml#/components/schemas/AssignableRole'
+ status:
+ type: string
+ enum: [pending, expired, declined]
+ description: >-
+ pending while it waits for an answer, expired once its seven days
+ ran out, declined when the person turned it down.
+ invitedBy:
+ $ref: '#/components/schemas/InvitationSender'
+ createdAt:
+ type: string
+ format: date-time
+ description: When it was sent.
+ expiresAt:
+ type: string
+ format: date-time
+ description: When it stops being accepted.
+ OrganizationInvitationPage:
+ type: object
+ required: [invitations, nextCursor]
+ properties:
+ invitations:
+ type: array
+ description: The newest first.
+ items:
+ $ref: '#/components/schemas/OrganizationInvitation'
+ nextCursor:
+ type: [string, 'null']
+ maxLength: 4096
+ pattern: ^[A-Za-z0-9_-]+$
+ description: >-
+ Pass as cursor for the next page. Null ends the list. Written in
+ URL-safe base64, the only form the cursor parameter accepts.
+ OrganizationInvitationResponse:
+ type: object
+ required: [invitation, delivery]
+ properties:
+ invitation:
+ $ref: '#/components/schemas/OrganizationInvitation'
+ delivery:
+ type: string
+ enum: [emailed, link]
+ description: >-
+ How the person hears of it. emailed when OpenBot sent them an
+ email. link when it could not or is not set up to, so the inviter
+ passes the invitation's link on themselves. Either way the person
+ sees the invitation in OpenBot when they sign in.
+ CreateOrganizationInvitationRequest:
type: object
additionalProperties: false
required: [email, role]
@@ -330,9 +884,74 @@ components:
minLength: 3
maxLength: 320
pattern: ^[^\s\x00]+@[^\s\x00]+$
- description: The address of somebody who already has an account here.
+ description: The address of the person to invite.
+ role:
+ $ref: './common.yaml#/components/schemas/AssignableRole'
+ Invitation:
+ type: object
+ description: >-
+ An invitation as the person it was sent to sees it. status is the
+ server's verdict.
+ required: [id, organization, role, status, invitedBy, createdAt, expiresAt]
+ properties:
+ id:
+ type: string
+ description: The invitation's id. Opaque.
+ organization:
+ type: object
+ description: The organization it is an invitation to.
+ required: [id, slug, name]
+ properties:
+ id:
+ type: string
+ description: The organization's id. Opaque.
+ slug:
+ type: string
+ description: Its short name.
+ name:
+ type: string
+ description: What people call it.
role:
$ref: './common.yaml#/components/schemas/AssignableRole'
+ status:
+ type: string
+ enum: [pending, expired, accepted, declined, canceled]
+ description: >-
+ pending while it can still be answered. expired once its seven
+ days ran out, accepted or declined once the person answered,
+ canceled when the organization took it back.
+ invitedBy:
+ $ref: '#/components/schemas/InvitationSender'
+ createdAt:
+ type: string
+ format: date-time
+ description: When it was sent.
+ expiresAt:
+ type: string
+ format: date-time
+ description: When it stops being accepted.
+ InvitationPage:
+ type: object
+ required: [invitations, nextCursor]
+ properties:
+ invitations:
+ type: array
+ description: The newest first.
+ items:
+ $ref: '#/components/schemas/Invitation'
+ nextCursor:
+ type: [string, 'null']
+ maxLength: 4096
+ pattern: ^[A-Za-z0-9_-]+$
+ description: >-
+ Pass as cursor for the next page. Null ends the list. Written in
+ URL-safe base64, the only form the cursor parameter accepts.
+ InvitationResponse:
+ type: object
+ required: [invitation]
+ properties:
+ invitation:
+ $ref: '#/components/schemas/Invitation'
responses:
InvalidOrganization:
description: The name or the slug is missing or malformed, or the Idempotency-Key is.
@@ -403,28 +1022,31 @@ components:
retryable: true
requestId: req_example
traceId: trace_example
- InvalidOrganizationMember:
- description: The address or the role is missing or malformed, or the Idempotency-Key is.
+ OwnerStays:
+ description: >-
+ The person stays in the organization: they own it, or this OpenBot's
+ settings keep them as an admin of it. The members list says who, as
+ removable.
content:
application/problem+json:
schema:
$ref: './common.yaml#/components/schemas/Problem'
examples:
- role:
+ owner:
value:
- type: https://open.bot/errors/validation-error
- title: Request validation failed.
- status: 400
- detail: A role of admin or member is required.
- code: VALIDATION_ERROR
- category: validation
+ type: https://open.bot/errors/conflict
+ title: The request conflicts with the current state.
+ status: 409
+ detail: They own this organization, so they stay a member of it.
+ code: CONFLICT
+ category: conflict
retryable: false
requestId: req_example
traceId: trace_example
- OrganizationOrPersonNotFound:
+ OrganizationOrInvitationNotFound:
description: >-
The organization does not exist or is not visible to the caller, or
- nobody here has that address.
+ it has no such invitation.
content:
application/problem+json:
schema:
@@ -441,21 +1063,89 @@ components:
retryable: false
requestId: req_example
traceId: trace_example
- person:
+ invitation:
value:
- type: https://open.bot/errors/person-not-found
- title: Person not found.
+ type: https://open.bot/errors/invitation-not-found
+ title: Invitation not found.
status: 404
- detail: Nobody here has that address. They need to sign in to OpenBot once first.
- code: PERSON_NOT_FOUND
+ detail: Couldn't find that invitation.
+ code: INVITATION_NOT_FOUND
category: not_found
retryable: false
requestId: req_example
traceId: trace_example
- OrganizationMemberConflict:
+ InvitationNotFound:
+ description: >-
+ There is no such invitation, or it was sent to another address.
+ content:
+ application/problem+json:
+ schema:
+ $ref: './common.yaml#/components/schemas/Problem'
+ examples:
+ invitation:
+ value:
+ type: https://open.bot/errors/invitation-not-found
+ title: Invitation not found.
+ status: 404
+ detail: Couldn't find that invitation. Check that you're signed in with the address it was sent to.
+ code: INVITATION_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ InvitationNotWaiting:
+ description: >-
+ The invitation expired, was canceled or was already answered. Or the
+ Idempotency-Key was used for a different request.
+ content:
+ application/problem+json:
+ schema:
+ $ref: './common.yaml#/components/schemas/Problem'
+ examples:
+ expired:
+ value:
+ type: https://open.bot/errors/conflict
+ title: The request conflicts with the current state.
+ status: 409
+ detail: This invitation has expired. Ask whoever invited you to send a new one.
+ code: CONFLICT
+ category: conflict
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ reused:
+ value:
+ type: https://open.bot/errors/idempotency-key-conflict
+ title: That Idempotency-Key was used for a different request.
+ status: 409
+ detail: That Idempotency-Key was used for a different request.
+ code: IDEMPOTENCY_KEY_CONFLICT
+ category: conflict
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ InvalidOrganizationInvitation:
+ description: The address or the role is missing or malformed, or the Idempotency-Key is.
+ content:
+ application/problem+json:
+ schema:
+ $ref: './common.yaml#/components/schemas/Problem'
+ examples:
+ role:
+ value:
+ type: https://open.bot/errors/validation-error
+ title: Request validation failed.
+ status: 400
+ detail: A role of admin or member is required.
+ code: VALIDATION_ERROR
+ category: validation
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ OrganizationInvitationConflict:
description: >-
- They are already a member. Or the Idempotency-Key was used for a
- different request.
+ They are already a member, or already have an invitation waiting. Or
+ the Idempotency-Key was used for a different request.
content:
application/problem+json:
schema:
@@ -472,6 +1162,17 @@ components:
retryable: false
requestId: req_example
traceId: trace_example
+ invited:
+ value:
+ type: https://open.bot/errors/conflict
+ title: The request conflicts with the current state.
+ status: 409
+ detail: They already have an invitation waiting. Cancel it to send a new one.
+ code: CONFLICT
+ category: conflict
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
reused:
value:
type: https://open.bot/errors/idempotency-key-conflict
@@ -485,19 +1186,21 @@ components:
traceId: trace_example
examples:
OrganizationPageLast:
- summary: Somebody in two organizations, working in the first.
+ summary: Somebody in their own organization and one they created, working in their own.
value:
organizations:
- - id: default
- slug: default
- name: Acme
- role: admin
+ - id: Wm4pZ7tKc1Xb9RnQ2sYd6hLe
+ slug: dana
+ name: Dana's organization
+ role: owner
active: true
+ personal: true
- id: Jq3xT9mLw2Vb8RnC5sYd0fKe
slug: acme-research
name: Acme Research
role: owner
active: false
+ personal: false
canCreate: true
nextCursor: null
CreatedOrganization:
@@ -509,6 +1212,7 @@ components:
name: Acme Research
role: owner
active: false
+ personal: false
OrganizationMemberPageLast:
summary: An organization's members, on one page.
value:
@@ -519,20 +1223,116 @@ components:
image: null
role: owner
joinedAt: '2026-11-14T09:12:40.000Z'
+ removable: false
+ assignableRoles: []
- id: 2fn8w1c6y4tq7h0mbe3s
email: sam.ortiz@acme.com
name: Sam Ortiz
image: null
role: member
joinedAt: '2026-11-14T09:20:05.000Z'
+ removable: true
+ assignableRoles: [owner, admin]
nextCursor: null
- AddedOrganizationMember:
- summary: Somebody added as a member.
+ PromotedOrganizationMember:
+ summary: A member an owner has made an owner too.
value:
member:
id: 2fn8w1c6y4tq7h0mbe3s
email: sam.ortiz@acme.com
name: Sam Ortiz
image: null
- role: member
+ role: owner
joinedAt: '2026-11-14T09:20:05.000Z'
+ removable: true
+ assignableRoles: [admin, member]
+ RenamedOrganization:
+ summary: An organization with its new name.
+ value:
+ organization:
+ id: Jq3xT9mLw2Vb8RnC5sYd0fKe
+ slug: acme-research
+ name: Acme Research Lab
+ role: owner
+ active: true
+ personal: false
+ JoinedOrganization:
+ summary: The organization somebody joined by accepting an invitation.
+ value:
+ organization:
+ id: Jq3xT9mLw2Vb8RnC5sYd0fKe
+ slug: acme-research
+ name: Acme Research
+ role: member
+ active: false
+ personal: false
+ OrganizationInvitationPageLast:
+ summary: One invitation waiting and one that expired.
+ value:
+ invitations:
+ - id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11
+ email: sam.ortiz@acme.com
+ role: member
+ status: pending
+ invitedBy:
+ name: Dana Whitfield
+ email: dana.whitfield@acme.com
+ createdAt: '2026-11-15T09:20:05.000Z'
+ expiresAt: '2026-11-22T09:20:05.000Z'
+ - id: 0c2d7a53-1f4e-4f0a-8a57-3d1b2c9e7f42
+ email: lee.park@acme.com
+ role: admin
+ status: expired
+ invitedBy:
+ name: Dana Whitfield
+ email: dana.whitfield@acme.com
+ createdAt: '2026-11-01T09:20:05.000Z'
+ expiresAt: '2026-11-08T09:20:05.000Z'
+ nextCursor: null
+ CreatedOrganizationInvitation:
+ summary: An invitation OpenBot could not email, so the inviter passes the link on.
+ value:
+ invitation:
+ id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11
+ email: sam.ortiz@acme.com
+ role: member
+ status: pending
+ invitedBy:
+ name: Dana Whitfield
+ email: dana.whitfield@acme.com
+ createdAt: '2026-11-15T09:20:05.000Z'
+ expiresAt: '2026-11-22T09:20:05.000Z'
+ delivery: link
+ InvitationPageLast:
+ summary: One invitation waiting for the caller.
+ value:
+ invitations:
+ - id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11
+ organization:
+ id: Jq3xT9mLw2Vb8RnC5sYd0fKe
+ slug: acme-research
+ name: Acme Research
+ role: member
+ status: pending
+ invitedBy:
+ name: Dana Whitfield
+ email: dana.whitfield@acme.com
+ createdAt: '2026-11-15T09:20:05.000Z'
+ expiresAt: '2026-11-22T09:20:05.000Z'
+ nextCursor: null
+ WaitingInvitation:
+ summary: An invitation the caller can still answer.
+ value:
+ invitation:
+ id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11
+ organization:
+ id: Jq3xT9mLw2Vb8RnC5sYd0fKe
+ slug: acme-research
+ name: Acme Research
+ role: member
+ status: pending
+ invitedBy:
+ name: Dana Whitfield
+ email: dana.whitfield@acme.com
+ createdAt: '2026-11-15T09:20:05.000Z'
+ expiresAt: '2026-11-22T09:20:05.000Z'
diff --git a/api/openapi/passwords-and-recorder.yaml b/api/openapi/passwords-and-recorder.yaml
index c4e866a491..8d90ac74d5 100644
--- a/api/openapi/passwords-and-recorder.yaml
+++ b/api/openapi/passwords-and-recorder.yaml
@@ -125,7 +125,10 @@ paths:
it has got to, the last thing that happened, and the usernames
of the person's saved logins for that site while the password
manager is on. Never a credential. Only the person it was opened
- for may read it; anybody else's is not found.
+ for may read it; anybody else's is not found. A request belongs to
+ the organization the Bot asked in, and is not found in any other, so
+ the link a Bot hands the person (/sign-in/{signInRequestId}) opens
+ only while they are working in that organization.
security:
- webSession: []
- appOAuth: [sign-in-requests:read]
@@ -822,7 +825,9 @@ paths:
description: >-
End the connection the request is signed with: the Recorder's
own Disconnect. Signed with the Recorder's connection token and
- nothing else.
+ nothing else. organizationId is `default` or the connection's own
+ organization, and either way the call acts in the connection's
+ organization.
security:
- recorderConnection: []
parameters:
@@ -856,7 +861,9 @@ paths:
description: >-
Return the person this Recorder's connection acts as, and the
connection's id. Signed with the Recorder's connection token and
- nothing else. A connection that has ended is refused as signed
+ nothing else. organizationId is `default` or the connection's own
+ organization, and either way the answer is for the connection's
+ organization. A connection that has ended is refused as signed
out, with why.
x-openbot-singleton: true
security:
@@ -897,6 +904,8 @@ paths:
Return whether the recordings this Recorder's person makes land
in their own Learning space, which is made on first need. Signed
with the Recorder's connection token and nothing else.
+ organizationId is `default` or the connection's own organization,
+ and either way the answer is for the connection's organization.
x-openbot-singleton: true
security:
- recorderConnection: []
@@ -938,7 +947,9 @@ paths:
a recording runs, so OpenBot can show a recording wherever the
person made it. Kept against the connection in place of the last
report, and never audited: it is a heartbeat. Signed with the
- Recorder's connection token and nothing else.
+ Recorder's connection token and nothing else. organizationId is
+ `default` or the connection's own organization, and either way the
+ report is kept in the connection's organization.
security:
- recorderConnection: []
parameters:
diff --git a/api/openapi/schedules.yaml b/api/openapi/schedules.yaml
index 189ee27bbe..fbb7e436b3 100644
--- a/api/openapi/schedules.yaml
+++ b/api/openapi/schedules.yaml
@@ -701,10 +701,11 @@ paths:
- Check-ins
operationId: getCheckInUsage
summary: Read how check-ins are going
- description: "Return, per Bot, over the last 7 or 30 days: how its check-ins
- ended, what they raised, what people did with it and how many notices
- carried it, with the daily limit in force. Counts only: no item's title,
- source or person. Only an administrator may read it."
+ description: "Return, per Bot in the organization, over the last 7 or 30
+ days: how its check-ins ended, what they raised, what people did with
+ it and how many notices carried it, with the organization's daily limit
+ in force. Counts only: no item's title, source or person. Only an
+ administrator of the organization may read it."
x-openbot-singleton: true
security:
- webSession: []
diff --git a/api/openapi/skills.yaml b/api/openapi/skills.yaml
index e95214d9a9..d1c9ee97c7 100644
--- a/api/openapi/skills.yaml
+++ b/api/openapi/skills.yaml
@@ -11,8 +11,12 @@ paths:
operationId: listSkills
summary: List skills
description: >-
- Return one page of the skills the caller can see: the organization's
- and their own. An admin sees everybody's. Ordered by title, then
+ Return one page of the skills the caller can see: their own, the
+ ones granted to a team they are in, and the organization's that are
+ granted to no team. An organization's skill granted to teams is
+ listed only to those teams' people. An admin of the organization
+ sees every skill.
+ Another organization's skills are never listed. Ordered by title, then
slug. A missing cursor starts at the first page and nextCursor null
ends the list.
security:
@@ -56,8 +60,8 @@ paths:
operationId: getSkill
summary: Read a skill
description: >-
- Return one skill the caller can see: the organization's or their own.
- An admin can read anybody's. Somebody else's skill is not found.
+ Return one skill the caller can see, as the list shows them. An admin
+ can read any. One the caller can't see is not found.
security:
- webSession: []
- appOAuth: [skills:read]
@@ -177,6 +181,99 @@ paths:
$ref: './common.yaml#/components/responses/ServerError'
default:
$ref: './common.yaml#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/skills/{skillId}/team-grants:
+ parameters:
+ - $ref: './common.yaml#/components/parameters/OrganizationId'
+ - $ref: '#/components/parameters/SkillId'
+ get:
+ tags: [Skills]
+ operationId: getSkillTeamGrants
+ summary: Read the teams the skill is granted to
+ description: >-
+ Return the teams the skill is granted to, by id. A person in one of those teams, or in a team beneath one, may put the skill on a Bot they own, and the Bot is offered it only while they stay in such a team. Only an admin
+ of the organization may read them.
+ x-openbot-singleton: true
+ security:
+ - webSession: []
+ - appOAuth: [skills:read]
+ - apiKey: []
+ responses:
+ '200':
+ description: The teams the skill is granted to.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SkillTeamGrants'
+ examples:
+ granted:
+ $ref: '#/components/examples/SkillTeamGrantsExample'
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/SkillOrTeamNotFound'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ put:
+ tags: [Skills]
+ operationId: replaceSkillTeamGrants
+ summary: Grant a skill to teams
+ description: >-
+ Grant the skill to exactly these teams of the organization, taking it
+ from any team left out. An empty list takes it from every team.
+ A person in one of those teams, or in a team beneath one, may put the skill on a Bot they own, and the Bot is offered it only while they stay in such a team. A team of another organization is not found. Only an admin
+ of the organization may do this. Recorded on the audit trail.
+ security:
+ - webSession: []
+ - appOAuth: [skills:write]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SkillTeamGrantsInput'
+ examples:
+ oneTeam:
+ value:
+ teams: [Tm4Qx8LpV2nWc7RbY1sKd0Ze]
+ responses:
+ '200':
+ description: The teams the skill is now granted to.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SkillTeamGrants'
+ examples:
+ granted:
+ $ref: '#/components/examples/SkillTeamGrantsExample'
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/AdminOnly'
+ '404':
+ $ref: '#/components/responses/SkillOrTeamNotFound'
+ '409':
+ $ref: './common.yaml#/components/responses/IdempotencyConflict'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
components:
parameters:
SkillId:
@@ -199,7 +296,7 @@ components:
description: >-
A named instruction a person runs with / in a conversation, on a Bot
that offers it.
- required: [slug, title, summary, instructions, tools, ownerId, botIds]
+ required: [slug, title, summary, instructions, tools, ownerId, botIds, usableOnYourBots]
properties:
slug:
type: string
@@ -229,6 +326,12 @@ components:
description: The Bots that offer it, by id.
items:
type: string
+ usableOnYourBots:
+ type: boolean
+ description: >-
+ Whether the caller may put it on a Bot they own: it is their own,
+ or it is granted to a team they are in. A Bot's Skills page offers
+ these.
SkillInput:
type: object
additionalProperties: false
@@ -263,6 +366,30 @@ components:
description: >-
Make a new skill the organization's. Only an admin may. It
applies when the skill is made: rewriting one keeps whose it is.
+ SkillTeamGrants:
+ type: object
+ description: The teams the skill is granted to.
+ required: [teams]
+ properties:
+ teams:
+ type: array
+ description: Each team's id, in order.
+ items:
+ type: string
+ SkillTeamGrantsInput:
+ type: object
+ additionalProperties: false
+ required: [teams]
+ properties:
+ teams:
+ type: array
+ maxItems: 100
+ description: The id of each team of this organization to grant it to.
+ items:
+ type: string
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
SkillPage:
type: object
required: [skills, nextCursor]
@@ -282,8 +409,8 @@ components:
responses:
SkillNotFound:
description: >-
- No skill has that slug, it is somebody else's and the caller isn't an
- admin, or the organization does not exist.
+ No skill has that slug, the caller isn't an admin and can't see it,
+ or the organization does not exist.
content:
application/problem+json:
schema:
@@ -300,6 +427,37 @@ components:
retryable: false
requestId: req_example
traceId: trace_example
+ SkillOrTeamNotFound:
+ description: >-
+ There is no skill by that slug, a team named is not one of this
+ organization's, or the organization does not exist.
+ content:
+ application/problem+json:
+ schema:
+ $ref: './common.yaml#/components/schemas/Problem'
+ examples:
+ skill:
+ value:
+ type: https://open.bot/errors/skill-not-found
+ title: Skill not found.
+ status: 404
+ detail: There is no skill called standup.
+ code: SKILL_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ team:
+ value:
+ type: https://open.bot/errors/team-not-found
+ title: Team not found.
+ status: 404
+ detail: Couldn't find that team.
+ code: TEAM_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
InvalidSkill:
description: >-
A field is missing, blank once trimmed or holds text that can't be
@@ -374,6 +532,7 @@ components:
tools: [google-calendar/list_events]
ownerId: user_3f1c9a
botIds: [general-assistant]
+ usableOnYourBots: true
- slug: weekly-report
title: Weekly report
summary: Sum up the week's work for the team.
@@ -381,7 +540,12 @@ components:
tools: []
ownerId: null
botIds: [general-assistant, research-assistant]
+ usableOnYourBots: false
nextCursor: null
+ SkillTeamGrantsExample:
+ summary: Granted to one team.
+ value:
+ teams: [Tm4Qx8LpV2nWc7RbY1sKd0Ze]
SkillExample:
summary: A person's own skill, offered by one Bot.
value:
@@ -392,3 +556,4 @@ components:
tools: [google-calendar/list_events]
ownerId: user_3f1c9a
botIds: [general-assistant]
+ usableOnYourBots: true
diff --git a/api/openapi/teams.yaml b/api/openapi/teams.yaml
new file mode 100644
index 0000000000..7e579c0511
--- /dev/null
+++ b/api/openapi/teams.yaml
@@ -0,0 +1,860 @@
+# Teams: the named groups of people inside one organization, and each team's members.
+#
+# One area of OpenBot's REST API. `bun run api:bundle` joins every area with common.yaml into
+# api/openapi.yaml, the file every client and check reads. See api/README.md.
+paths:
+ /api/v2/organizations/{organizationId}/teams:
+ parameters:
+ - $ref: './common.yaml#/components/parameters/OrganizationId'
+ get:
+ tags: [Teams]
+ operationId: listTeams
+ summary: List an organization's teams
+ description: >-
+ Return one page of the organization's teams, in the order they were
+ created. Any member of the organization can read it. Each team says
+ the caller's own role in it and whether the caller may manage it. A
+ missing cursor starts at the first page and nextCursor null ends the
+ list.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:read]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/Limit'
+ - $ref: './common.yaml#/components/parameters/Cursor'
+ responses:
+ '200':
+ description: One page of teams.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TeamPage'
+ examples:
+ lastPage:
+ $ref: '#/components/examples/TeamPageLast'
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/Forbidden'
+ '404':
+ $ref: './common.yaml#/components/responses/OrganizationNotFound'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ post:
+ tags: [Teams]
+ operationId: createTeam
+ summary: Create a team
+ description: >-
+ Create a team in the organization. Only an owner or an admin of the
+ organization can. A team's name is unique in its organization,
+ whatever its case. A team may sit under a parent team, and then its
+ members can use everything granted to the parent as well. A repeated
+ request with the same Idempotency-Key and body returns the first
+ result.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:write]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateTeamRequest'
+ examples:
+ named:
+ value:
+ name: Sales
+ description: Everybody who sells.
+ responses:
+ '201':
+ description: The team was created.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ Location:
+ description: The new team.
+ schema:
+ type: string
+ example: /api/v2/organizations/default/teams/Tm4Qx8LpV2nWc7RbY1sKd0Ze
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TeamResponse'
+ examples:
+ created:
+ $ref: '#/components/examples/CreatedTeam'
+ '400':
+ $ref: '#/components/responses/InvalidTeam'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/AdminOnly'
+ '404':
+ $ref: './common.yaml#/components/responses/OrganizationNotFound'
+ '409':
+ $ref: '#/components/responses/TeamConflict'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/teams/{teamId}:
+ parameters:
+ - $ref: './common.yaml#/components/parameters/OrganizationId'
+ - $ref: '#/components/parameters/TeamId'
+ get:
+ tags: [Teams]
+ operationId: getTeam
+ summary: Read one team
+ description: >-
+ Return one of the organization's teams. Any member of the
+ organization can read it. A team of another organization is not
+ found.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:read]
+ - apiKey: []
+ responses:
+ '200':
+ description: The team.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TeamResponse'
+ examples:
+ team:
+ $ref: '#/components/examples/CreatedTeam'
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/Forbidden'
+ '404':
+ $ref: '#/components/responses/TeamNotFound'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ patch:
+ tags: [Teams]
+ operationId: updateTeam
+ summary: Change a team
+ description: >-
+ Change a team's name, its description or its parent team; a field
+ that is absent stays as it is, and a null parent takes the team out
+ from under its parent. An owner or an admin of the organization can,
+ and so can one of the team's maintainers, except that only an owner
+ or an admin changes its parent. A team that comes from the company's
+ directory keeps the directory's name. A team can't be put under
+ itself or under a team beneath it.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:write]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateTeamRequest'
+ examples:
+ renamed:
+ value:
+ name: Sales EMEA
+ responses:
+ '200':
+ description: The team as it now is.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TeamResponse'
+ examples:
+ changed:
+ $ref: '#/components/examples/CreatedTeam'
+ '400':
+ $ref: '#/components/responses/InvalidTeam'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/TeamForbidden'
+ '404':
+ $ref: '#/components/responses/TeamNotFound'
+ '409':
+ $ref: '#/components/responses/TeamConflict'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ delete:
+ tags: [Teams]
+ operationId: deleteTeam
+ summary: Delete a team
+ description: >-
+ Delete a team. Its members stay in the organization and lose what
+ was granted to the team, at once. Teams under it move up to its own
+ parent. Only an owner or an admin of the organization can. A team
+ that comes from the company's directory is removed there, not here.
+ Deleting a team that is not there changes nothing.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:write]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/IdempotencyKey'
+ responses:
+ '204':
+ description: The team is gone.
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/TeamForbidden'
+ '404':
+ $ref: './common.yaml#/components/responses/OrganizationNotFound'
+ '409':
+ $ref: './common.yaml#/components/responses/IdempotencyConflict'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/teams/{teamId}/members:
+ parameters:
+ - $ref: './common.yaml#/components/parameters/OrganizationId'
+ - $ref: '#/components/parameters/TeamId'
+ get:
+ tags: [Teams]
+ operationId: listTeamMembers
+ summary: List a team's members
+ description: >-
+ Return one page of the people in a team, in the order they joined
+ it. Any member of the organization can read it. People who are only
+ in a team beneath this one are not listed. A missing cursor starts at
+ the first page and nextCursor null ends the list.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:read]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/Limit'
+ - $ref: './common.yaml#/components/parameters/Cursor'
+ responses:
+ '200':
+ description: One page of the team's members.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TeamMemberPage'
+ examples:
+ lastPage:
+ $ref: '#/components/examples/TeamMemberPageLast'
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: './common.yaml#/components/responses/Forbidden'
+ '404':
+ $ref: '#/components/responses/TeamNotFound'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ /api/v2/organizations/{organizationId}/teams/{teamId}/members/{memberId}:
+ parameters:
+ - $ref: './common.yaml#/components/parameters/OrganizationId'
+ - $ref: '#/components/parameters/TeamId'
+ - $ref: '#/components/parameters/TeamMemberId'
+ put:
+ tags: [Teams]
+ operationId: putTeamMember
+ summary: Add a person to a team, or change their role in it
+ description: >-
+ Put a member of the organization in the team with a role, or change
+ the role of somebody already in it. What is granted to the team is
+ theirs from their next request. An owner or an admin of the
+ organization can, and so can one of the team's maintainers. A team
+ that comes from the company's directory takes its people from the
+ directory, so nobody is added to it here.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:write]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/IdempotencyKey'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PutTeamMemberRequest'
+ examples:
+ member:
+ value:
+ role: member
+ responses:
+ '200':
+ description: The person as a member of the team.
+ headers:
+ Cache-Control:
+ $ref: './common.yaml#/components/headers/PrivateNoStore'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TeamMemberResponse'
+ examples:
+ added:
+ $ref: '#/components/examples/AddedTeamMember'
+ '400':
+ $ref: '#/components/responses/InvalidTeamMember'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/TeamForbidden'
+ '404':
+ $ref: '#/components/responses/TeamOrPersonNotFound'
+ '409':
+ $ref: './common.yaml#/components/responses/IdempotencyConflict'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+ delete:
+ tags: [Teams]
+ operationId: removeTeamMember
+ summary: Take a person out of a team
+ description: >-
+ Take a person out of the team. They stay in the organization and
+ lose what was granted to the team from their next request. An owner
+ or an admin of the organization can, so can one of the team's
+ maintainers, and anybody can take themselves out. A team that comes
+ from the company's directory takes its people from the directory, so
+ nobody is removed from it here. Removing somebody who is not in the
+ team changes nothing.
+ security:
+ - webSession: []
+ - appOAuth: [organizations:write]
+ - apiKey: []
+ parameters:
+ - $ref: './common.yaml#/components/parameters/IdempotencyKey'
+ responses:
+ '204':
+ description: They are not in the team.
+ '400':
+ $ref: './common.yaml#/components/responses/InvalidRequest'
+ '401':
+ $ref: './common.yaml#/components/responses/Unauthenticated'
+ '403':
+ $ref: '#/components/responses/TeamForbidden'
+ '404':
+ $ref: '#/components/responses/TeamNotFound'
+ '409':
+ $ref: './common.yaml#/components/responses/IdempotencyConflict'
+ '500':
+ $ref: './common.yaml#/components/responses/ServerError'
+ default:
+ $ref: './common.yaml#/components/responses/UnexpectedError'
+components:
+ parameters:
+ TeamId:
+ name: teamId
+ in: path
+ required: true
+ description: The team's id. Opaque.
+ schema:
+ type: string
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
+ example: Tm4Qx8LpV2nWc7RbY1sKd0Ze
+ TeamMemberId:
+ name: memberId
+ in: path
+ required: true
+ description: The person's id, or me for the caller.
+ schema:
+ type: string
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
+ example: 2fn8w1c6y4tq7h0mbe3s
+ schemas:
+ TeamRole:
+ type: string
+ description: >-
+ A person's role in a team. A maintainer can rename the team and add
+ and remove its people; a member cannot.
+ enum: [maintainer, member]
+ TeamSource:
+ type: string
+ description: >-
+ Where a team comes from. openbot is a team made here. directory is a
+ group of the company's directory, kept in step with it: its name and
+ its people are the directory's and can't be changed here.
+ enum: [openbot, directory]
+ Team:
+ type: object
+ description: >-
+ One team of an organization, as one of the organization's members
+ sees it. role and canManage are the server's verdicts about the
+ caller.
+ required:
+ - id
+ - name
+ - description
+ - parentTeamId
+ - source
+ - memberCount
+ - role
+ - canManage
+ - canMove
+ - canDelete
+ - createdAt
+ properties:
+ id:
+ type: string
+ description: The team's id. Opaque.
+ name:
+ type: string
+ description: What people call it. Unique in its organization.
+ description:
+ type: [string, 'null']
+ description: What the team is for, when somebody has said.
+ parentTeamId:
+ type: [string, 'null']
+ description: >-
+ The team this one sits under, whose grants its members also have.
+ Null for a team under none.
+ source:
+ $ref: '#/components/schemas/TeamSource'
+ memberCount:
+ type: integer
+ minimum: 0
+ description: How many people are in the team itself.
+ role:
+ oneOf:
+ - $ref: '#/components/schemas/TeamRole'
+ - type: 'null'
+ description: The caller's role in the team. Null when they are not in it.
+ canManage:
+ type: boolean
+ description: >-
+ Whether the caller may rename the team and add and remove its
+ people: the server's verdict.
+ canMove:
+ type: boolean
+ description: >-
+ Whether the caller may put the team under another team or take
+ it out from under one: the server's verdict, true for an owner
+ or an admin of the organization.
+ canDelete:
+ type: boolean
+ description: >-
+ Whether the caller may delete the team: the server's verdict,
+ true for an owner or an admin of the organization, and never for
+ a team that comes from the company's directory.
+ createdAt:
+ type: string
+ format: date-time
+ description: When the team was created.
+ TeamPage:
+ type: object
+ required: [teams, canCreate, nextCursor]
+ properties:
+ teams:
+ type: array
+ description: In the order they were created.
+ items:
+ $ref: '#/components/schemas/Team'
+ canCreate:
+ type: boolean
+ description: >-
+ Whether the caller may create a team here: the server's verdict.
+ The same on every page.
+ nextCursor:
+ type: [string, 'null']
+ maxLength: 4096
+ pattern: ^[A-Za-z0-9_-]+$
+ description: >-
+ Pass as cursor for the next page. Null ends the list. Written in
+ URL-safe base64, the only form the cursor parameter accepts.
+ TeamResponse:
+ type: object
+ required: [team]
+ properties:
+ team:
+ $ref: '#/components/schemas/Team'
+ CreateTeamRequest:
+ type: object
+ additionalProperties: false
+ required: [name]
+ properties:
+ name:
+ type: string
+ minLength: 1
+ maxLength: 100
+ pattern: ^[^\x00]*\S[^\x00]*$
+ description: What people call it.
+ description:
+ type: string
+ maxLength: 500
+ pattern: ^[^\x00]*$
+ description: What the team is for.
+ parentTeamId:
+ type: string
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
+ description: A team of the same organization to put this one under.
+ UpdateTeamRequest:
+ type: object
+ additionalProperties: false
+ minProperties: 1
+ properties:
+ name:
+ type: string
+ minLength: 1
+ maxLength: 100
+ pattern: ^[^\x00]*\S[^\x00]*$
+ description: What people call it.
+ description:
+ type: [string, 'null']
+ maxLength: 500
+ pattern: ^[^\x00]*$
+ description: What the team is for. Null clears it.
+ parentTeamId:
+ type: [string, 'null']
+ minLength: 1
+ maxLength: 200
+ pattern: ^[A-Za-z0-9_-]+$
+ description: >-
+ A team of the same organization to put this one under. Null takes
+ it out from under its parent.
+ TeamMember:
+ type: object
+ description: One person in a team.
+ required: [id, email, name, image, role, isCaller, joinedAt]
+ properties:
+ id:
+ type: string
+ description: The person's id.
+ email:
+ type: string
+ description: Their address.
+ name:
+ type: [string, 'null']
+ description: What OpenBot calls them. Null until they choose.
+ image:
+ type: [string, 'null']
+ description: Their picture's address, when they have one.
+ role:
+ $ref: '#/components/schemas/TeamRole'
+ isCaller:
+ type: boolean
+ description: Whether this person is the caller.
+ joinedAt:
+ type: string
+ format: date-time
+ description: When they joined the team.
+ TeamMemberPage:
+ type: object
+ required: [members, nextCursor]
+ properties:
+ members:
+ type: array
+ description: In the order they joined the team.
+ items:
+ $ref: '#/components/schemas/TeamMember'
+ nextCursor:
+ type: [string, 'null']
+ maxLength: 4096
+ pattern: ^[A-Za-z0-9_-]+$
+ description: >-
+ Pass as cursor for the next page. Null ends the list. Written in
+ URL-safe base64, the only form the cursor parameter accepts.
+ TeamMemberResponse:
+ type: object
+ required: [member]
+ properties:
+ member:
+ $ref: '#/components/schemas/TeamMember'
+ PutTeamMemberRequest:
+ type: object
+ additionalProperties: false
+ required: [role]
+ properties:
+ role:
+ $ref: '#/components/schemas/TeamRole'
+ responses:
+ InvalidTeam:
+ description: >-
+ The name, the description or the parent is missing or malformed, the
+ parent is not a team that can hold this one, or the Idempotency-Key
+ is malformed.
+ content:
+ application/problem+json:
+ schema:
+ $ref: './common.yaml#/components/schemas/Problem'
+ examples:
+ name:
+ value:
+ type: https://open.bot/errors/validation-error
+ title: Request validation failed.
+ status: 400
+ detail: A name of 1 to 100 characters is required.
+ code: VALIDATION_ERROR
+ category: validation
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ parent:
+ value:
+ type: https://open.bot/errors/validation-error
+ title: Request validation failed.
+ status: 400
+ detail: A team can't sit under itself or under a team beneath it.
+ code: VALIDATION_ERROR
+ category: validation
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ InvalidTeamMember:
+ description: The role is missing or malformed, or the Idempotency-Key is.
+ content:
+ application/problem+json:
+ schema:
+ $ref: './common.yaml#/components/schemas/Problem'
+ examples:
+ role:
+ value:
+ type: https://open.bot/errors/validation-error
+ title: Request validation failed.
+ status: 400
+ detail: A role of maintainer or member is required.
+ code: VALIDATION_ERROR
+ category: validation
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ TeamForbidden:
+ description: >-
+ The caller may not change this team: they are neither an owner or an
+ admin of the organization nor one of the team's maintainers. Or the
+ team comes from the company's directory, which is where it is
+ changed.
+ content:
+ application/problem+json:
+ schema:
+ $ref: './common.yaml#/components/schemas/Problem'
+ examples:
+ notAllowed:
+ value:
+ type: https://open.bot/errors/permission-denied
+ title: Permission denied.
+ status: 403
+ detail: Only an admin of this organization or a maintainer of this team can change it.
+ code: PERMISSION_DENIED
+ category: permission
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ directory:
+ value:
+ type: https://open.bot/errors/permission-denied
+ title: Permission denied.
+ status: 403
+ detail: This team comes from your company's directory. Change its people there.
+ code: PERMISSION_DENIED
+ category: permission
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ TeamNotFound:
+ description: >-
+ The organization or the team does not exist or is not visible to the
+ caller.
+ content:
+ application/problem+json:
+ schema:
+ $ref: './common.yaml#/components/schemas/Problem'
+ examples:
+ organization:
+ value:
+ type: https://open.bot/errors/organization-not-found
+ title: Organization not found.
+ status: 404
+ detail: Couldn't find that organization.
+ code: ORGANIZATION_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ team:
+ value:
+ type: https://open.bot/errors/team-not-found
+ title: Team not found.
+ status: 404
+ detail: Couldn't find that team.
+ code: TEAM_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ TeamOrPersonNotFound:
+ description: >-
+ The organization or the team does not exist or is not visible to the
+ caller, or the person is not a member of the organization.
+ content:
+ application/problem+json:
+ schema:
+ $ref: './common.yaml#/components/schemas/Problem'
+ examples:
+ team:
+ value:
+ type: https://open.bot/errors/team-not-found
+ title: Team not found.
+ status: 404
+ detail: Couldn't find that team.
+ code: TEAM_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ person:
+ value:
+ type: https://open.bot/errors/person-not-found
+ title: Person not found.
+ status: 404
+ detail: They aren't a member of this organization. Add them to the organization first.
+ code: PERSON_NOT_FOUND
+ category: not_found
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ TeamConflict:
+ description: >-
+ Another team of the organization has that name. Or the
+ Idempotency-Key was used for a different request.
+ content:
+ application/problem+json:
+ schema:
+ $ref: './common.yaml#/components/schemas/Problem'
+ examples:
+ nameTaken:
+ value:
+ type: https://open.bot/errors/conflict
+ title: The request conflicts with the current state.
+ status: 409
+ detail: Another team here already has that name. Choose another.
+ code: CONFLICT
+ category: conflict
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ reused:
+ value:
+ type: https://open.bot/errors/idempotency-key-conflict
+ title: That Idempotency-Key was used for a different request.
+ status: 409
+ detail: That Idempotency-Key was used for a different request.
+ code: IDEMPOTENCY_KEY_CONFLICT
+ category: conflict
+ retryable: false
+ requestId: req_example
+ traceId: trace_example
+ examples:
+ TeamPageLast:
+ summary: An organization's teams, on one page.
+ value:
+ teams:
+ - id: Tm4Qx8LpV2nWc7RbY1sKd0Ze
+ name: Sales
+ description: Everybody who sells.
+ parentTeamId: null
+ source: openbot
+ memberCount: 2
+ role: maintainer
+ canManage: true
+ canMove: true
+ canDelete: true
+ createdAt: '2026-11-15T09:12:40.000Z'
+ - id: Fn2Wc6Yt4Qh7M0be3sKq8xLp
+ name: Finance
+ description: null
+ parentTeamId: null
+ source: directory
+ memberCount: 1
+ role: null
+ canManage: false
+ canMove: true
+ canDelete: false
+ createdAt: '2026-11-15T09:20:05.000Z'
+ canCreate: true
+ nextCursor: null
+ CreatedTeam:
+ summary: A team made in OpenBot.
+ value:
+ team:
+ id: Tm4Qx8LpV2nWc7RbY1sKd0Ze
+ name: Sales
+ description: Everybody who sells.
+ parentTeamId: null
+ source: openbot
+ memberCount: 0
+ role: null
+ canManage: true
+ canMove: true
+ canDelete: true
+ createdAt: '2026-11-15T09:12:40.000Z'
+ TeamMemberPageLast:
+ summary: A team's people, on one page.
+ value:
+ members:
+ - id: 8kq2m4x7p1rvz3a9c5d0
+ email: dana.whitfield@acme.com
+ name: Dana Whitfield
+ image: null
+ role: maintainer
+ isCaller: true
+ joinedAt: '2026-11-15T09:13:02.000Z'
+ - id: 2fn8w1c6y4tq7h0mbe3s
+ email: sam.ortiz@acme.com
+ name: Sam Ortiz
+ image: null
+ role: member
+ isCaller: false
+ joinedAt: '2026-11-15T09:20:05.000Z'
+ nextCursor: null
+ AddedTeamMember:
+ summary: Somebody put in a team.
+ value:
+ member:
+ id: 2fn8w1c6y4tq7h0mbe3s
+ email: sam.ortiz@acme.com
+ name: Sam Ortiz
+ image: null
+ role: member
+ isCaller: false
+ joinedAt: '2026-11-15T09:20:05.000Z'
diff --git a/api/redocly/rules.mjs b/api/redocly/rules.mjs
index d815949eb4..e62ffc9834 100644
--- a/api/redocly/rules.mjs
+++ b/api/redocly/rules.mjs
@@ -14,11 +14,18 @@ import { parse } from "yaml";
const ORGANIZATION_PREFIX = "/api/v2/organizations/{organizationId}/";
/**
- * The one address outside an organization: the organizations the caller is a member of, and
- * creating one. A person has to be able to ask which organizations they are in before they can
- * name one, so this cannot sit under an organization's address.
+ * The addresses outside an organization. The organizations the caller is a member of, and
+ * creating one: a person has to be able to ask which organizations they are in before they can
+ * name one. And the invitations sent to the caller: they answer one before they are a member of
+ * the organization it is for, so neither can sit under an organization's address.
*/
-const OUTSIDE_AN_ORGANIZATION = ["/api/v2/people/me/organizations"];
+const OUTSIDE_AN_ORGANIZATION = [
+ "/api/v2/people/me/organizations",
+ "/api/v2/people/me/invitations",
+ "/api/v2/people/me/invitations/{invitationId}",
+ "/api/v2/people/me/invitations/{invitationId}/accept",
+ "/api/v2/people/me/invitations/{invitationId}/decline",
+];
const WRITE_METHODS = ["post", "put", "patch", "delete"];
const METHODS = ["get", "head", "options", "trace", ...WRITE_METHODS];
const PROBLEM_JSON = "application/problem+json";
diff --git a/api/redocly/rules.test.ts b/api/redocly/rules.test.ts
index 995e4f64f6..312fc2440e 100644
--- a/api/redocly/rules.test.ts
+++ b/api/redocly/rules.test.ts
@@ -1,4 +1,4 @@
-import { afterAll, expect, test } from "bun:test";
+import { afterAll, expect, setDefaultTimeout, test } from "bun:test";
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -12,6 +12,13 @@ import { parse, stringify } from "yaml";
* than letting the break through review.
*/
+/*
+ * Each lint is one run of the CLI over the whole spec: about 1 s on a laptop and 2.4 to 2.7 s on a CI
+ * runner, so a test that lints twice took 4.7 s there and one ran past Bun's 5 s default. Twenty
+ * seconds is four times the slowest seen.
+ */
+setDefaultTimeout(20_000);
+
const ROOT = join(import.meta.dir, "../..");
const SPEC = join(ROOT, "api/openapi.yaml");
const work = mkdtempSync(join(tmpdir(), "openbot-api-lint-"));
@@ -86,10 +93,14 @@ test("each convention is enforced", () => {
}
});
-test("only the caller's own organizations sit outside an organization", () => {
+test("only the caller's own organizations and invitations sit outside an organization", () => {
const ORGANIZATIONS = "/api/v2/people/me/organizations";
- // The one address a person can ask before they can name an organization: allowed as committed.
+ // What a person can ask before they can name an organization, or before they are a member of
+ // the one an invitation is for: allowed as committed.
expect(Object.keys(spec().paths)).toContain(ORGANIZATIONS);
+ expect(Object.keys(spec().paths)).toContain(
+ "/api/v2/people/me/invitations/{invitationId}/accept",
+ );
const broken = spec();
// Nothing beside it is: not another of the person's own resources, and not the address under it.
broken.paths["/api/v2/people/me/bots"] = broken.paths[BOTS];
diff --git a/app/src/components/admin/admin-sections.ts b/app/src/components/admin/admin-sections.ts
index aad35752f2..ba148f932b 100644
--- a/app/src/components/admin/admin-sections.ts
+++ b/app/src/components/admin/admin-sections.ts
@@ -7,6 +7,7 @@ import {
IconLockAccess,
IconShieldCheck,
IconUsers,
+ IconUsersGroup,
IconZoomQuestion,
} from "@tabler/icons-react";
import type { LinkOptions } from "@tanstack/react-router";
@@ -28,7 +29,8 @@ const team = managePaths("team");
/**
* Admin's pages, grouped by the thing a Bot has that each one sets for everybody, in the fixed order
- * of `lib/primitives.ts`, then Vault, then the team itself. The sidebar and the overview both draw
+ * of `lib/primitives.ts`, then Vault, then the organization itself: its people and the teams they are
+ * in, what they may do, and how they sign in. The sidebar and the overview both draw
* this list, so the two can never disagree about where a page is.
*
* Conversations has no group: it is where work happens, not something to set. Memory has none
@@ -144,14 +146,14 @@ export const ADMIN_SECTIONS: readonly AdminSection[] = [
items: [
{
title: team.credentialsLabel,
- description: "Manage this deployment’s keys and tokens.",
+ description: "Manage this organization’s keys and tokens.",
icon: VAULT.icon,
linkOptions: team.credentials(),
},
],
},
{
- title: "Team",
+ title: "Organization",
items: [
{
title: "People",
@@ -159,6 +161,13 @@ export const ADMIN_SECTIONS: readonly AdminSection[] = [
icon: IconUsers,
linkOptions: { to: "/admin/people" },
},
+ {
+ title: "Teams",
+ description: "Put people in teams, and give a team its own Bots.",
+ icon: IconUsersGroup,
+ /* Everybody's page, outside Admin: an admin does there what the server lets an admin do. */
+ linkOptions: { to: "/teams" },
+ },
{
title: "Permissions",
description:
diff --git a/app/src/components/admin/controls/capabilities-section.tsx b/app/src/components/admin/controls/capabilities-section.tsx
index dd9b0b2cdd..8853deaa72 100644
--- a/app/src/components/admin/controls/capabilities-section.tsx
+++ b/app/src/components/admin/controls/capabilities-section.tsx
@@ -4,7 +4,7 @@ import {
IconToggleRight,
IconUsersGroup,
} from "@tabler/icons-react";
-import { useMutation } from "@tanstack/react-query";
+import { useMutation, useQuery } from "@tanstack/react-query";
import { Link } from "@tanstack/react-router";
import { useState } from "react";
import { PageRows } from "@/components/layout/page-shell";
@@ -37,13 +37,18 @@ import {
import { Separator } from "@/components/ui/separator";
import { Switch } from "@/components/ui/switch";
import { setCapabilityMutationOptions } from "@/lib/enterprise/mutations";
-import type { EnterpriseOverview } from "@/lib/enterprise/queries";
+import type {
+ CapabilitySetting,
+ EnterpriseOverview,
+} from "@/lib/enterprise/queries";
+import { MISSING_TEAM } from "@/lib/teams/names";
+import { teamListQueryOptions } from "@/lib/teams/queries";
import { queryClient } from "@/query-client";
import { ControlsSection } from "./controls-section";
/**
* Admin, Permissions: what people may do, for the whole organization, with the row that opens the
- * overrides for roles and directory groups. The page's only section, so it has no title of its own.
+ * overrides for roles and teams. The page's only section, so it has no title of its own.
*/
export function CapabilitiesSection() {
const [overridesOpen, setOverridesOpen] = useState(false);
@@ -54,6 +59,7 @@ export function CapabilitiesSection() {
(count, capability) =>
count +
Object.keys(capability.roles).length +
+ Object.keys(capability.teams).length +
Object.keys(capability.groups).length,
0,
);
@@ -73,7 +79,7 @@ export function CapabilitiesSection() {
{effective
? capability.description
- : "Off for everybody, unless a role or group turns it on."}
+ : "Off for everybody, unless a role or team turns it on."}
@@ -104,7 +110,7 @@ export function CapabilitiesSection() {
- Role and group overrides
+ Role and team overrides
{overrideCount === 0
? "None. Everybody gets the switches above"
@@ -148,6 +154,38 @@ export function CapabilitiesSection() {
type Tri = "inherit" | "on" | "off";
+/** Whose switches the dialog is showing: a role's, a team's, or a directory group's. */
+type Scope = { kind: "role" | "team" | "group"; id: string; label: string };
+
+const scopeKey = (scope: Scope) => `${scope.kind}:${scope.id}`;
+
+/** What a scope set a permission to, or undefined where it sets nothing. */
+function storedAt(
+ capability: CapabilitySetting,
+ scope: Scope,
+): boolean | undefined {
+ if (scope.kind === "role")
+ return capability.roles[scope.id as "admin" | "member"];
+ return (scope.kind === "team" ? capability.teams : capability.groups)[
+ scope.id
+ ];
+}
+
+const SCOPE_HINTS: Record = {
+ role: "A role's setting replaces the organization switch for everybody with that role.",
+ team: "A team can only add. Grant gives the people in it, and in the teams beneath it, the permission even when the organization has it off.",
+ group:
+ "This rule is for a directory group. You can remove it here. Make new rules for a team.",
+};
+
+/**
+ * The switches a role or a team sets over the organization's.
+ *
+ * A team is picked by name from the organization's teams, and its id is what a switch is saved
+ * under. Two kinds of rule are listed only because they are already there, so that nothing is lost
+ * and each can be removed: a directory group's, from before there were teams, and one for a team
+ * that has since been deleted. Neither can be given a new permission here.
+ */
function OverridesDialog({
data,
open,
@@ -158,38 +196,67 @@ function OverridesDialog({
onOpenChange: (open: boolean) => void;
}) {
const setCapability = useMutation(setCapabilityMutationOptions(queryClient));
- const scopes: { kind: "role" | "group"; id: string; label: string }[] = [
+ const teams = useQuery({ ...teamListQueryOptions(), enabled: open });
+ const known = teams.data?.teams ?? [];
+ const named = (level: "teams" | "groups") => [
+ ...new Set(
+ data.capabilities.flatMap((capability) => Object.keys(capability[level])),
+ ),
+ ];
+ const scopes: Scope[] = [
{ kind: "role", id: "admin", label: "Admins" },
{ kind: "role", id: "member", label: "Members" },
- ...data.groups.map((group) => ({
+ ...known.map((team) => ({
+ kind: "team" as const,
+ id: team.id,
+ label: `Team: ${team.name}`,
+ })),
+ // Only once the teams are known: until then a team with a rule can't be told from a deleted one.
+ ...(teams.data
+ ? named("teams")
+ .filter((id) => !known.some((team) => team.id === id))
+ .map((id) => ({ kind: "team" as const, id, label: MISSING_TEAM }))
+ : []),
+ ...named("groups").map((group) => ({
kind: "group" as const,
id: group,
label: `Group: ${group}`,
})),
];
- const [scopeIndex, setScopeIndex] = useState(0);
- const scope = scopes[scopeIndex] ?? scopes[0];
+ const [chosen, setChosen] = useState("role:admin");
+ // A scope whose last rule was removed is no longer listed, so the dialog goes back to the first.
+ const scope =
+ scopes.find((candidate) => scopeKey(candidate) === chosen) ??
+ (scopes[0] as Scope);
+ /* Whether the scope is listed for the rules it already has, and not to be given new ones. */
+ const onlyItsRules =
+ scope.kind === "group" ||
+ (scope.kind === "team" && !known.some((team) => team.id === scope.id));
return (
) : skills.length === 0 ? (
- Skills you write show up here.
+ Skills you write, and skills an admin gives your team, show up here.
) : (
@@ -385,7 +383,7 @@ function Granted({
if (!plugins.data) {
return (
- Couldn't load what this Bot can use. Reload the page.
+ Couldn't load what this Bot can use. Try again in a moment.
- Couldn't load this Bot's activity. Reload the page.
+ Couldn't load this Bot's activity. Try again in a moment.
);
@@ -459,7 +459,7 @@ export function BotActivitySections({
{/* The tasks failing to load leaves the rest listed, and says which part is missing. */}
{taskList.error ? (
- Couldn't load this Bot's tasks. Reload the page.
+ Couldn't load this Bot's tasks. Try again in a moment.
) : null}
{groups.length === 0 && !taskList.error ? (
diff --git a/app/src/components/bot-profile/attention.tsx b/app/src/components/bot-profile/attention.tsx
index 41c2bdc2cf..a4a026a291 100644
--- a/app/src/components/bot-profile/attention.tsx
+++ b/app/src/components/bot-profile/attention.tsx
@@ -47,6 +47,24 @@ export function waitingOnYou(bot: BotAttention): number {
return asksOf(bot) + bot.tasks.ready + bot.tasks.failed;
}
+/**
+ * How many things wait on the person across all their Bots: the one number every badge, bell and tab
+ * shows, in OpenBot's sidebar and in every skin. Counted once, by the server's rule (`waitingOnYou`
+ * per Bot), so a skin never counts its own way: one that counted the approval inbox said 1 while
+ * the Bots badge said 2, because a failed task or a task waiting on a question is in one and not the
+ * other.
+ */
+export function waitingAcross(
+ bots: readonly BotAttention[] | undefined,
+): number {
+ return (bots ?? []).reduce((total, bot) => total + waitingOnYou(bot), 0);
+}
+
+/** {@link waitingAcross}, read live, for whatever draws the number. */
+export function useWaitingCount(): number {
+ return waitingAcross(useQuery(botAttentionQueryOptions()).data);
+}
+
const count = (total: number, one: string, many: string) =>
`${total} ${total === 1 ? one : many}`;
@@ -266,7 +284,7 @@ export function BotsNavBadge({ onIcon = false }: { onIcon?: boolean } = {}) {
useAttentionNotifications(attention.data);
usePingNotifications(lastPing.data, attention.data);
const bots = attention.data ?? [];
- const waiting = bots.reduce((total, bot) => total + waitingOnYou(bot), 0);
+ const waiting = waitingAcross(bots);
if (waiting > 0) {
return (
- Couldn't load this Bot's settings. Reload the page.
+ Couldn't load this Bot's settings. Try again in a moment.
) : (
diff --git a/app/src/components/bot-profile/sharing.tsx b/app/src/components/bot-profile/sharing.tsx
index 89f1406417..cc1cf1adde 100644
--- a/app/src/components/bot-profile/sharing.tsx
+++ b/app/src/components/bot-profile/sharing.tsx
@@ -15,6 +15,7 @@ import {
} from "@/components/layout/page-shell";
import { SharedAppNotice } from "@/components/plugins/shared-app-notice";
import { Button } from "@/components/ui/button";
+import { Checkbox } from "@/components/ui/checkbox";
import {
Dialog,
DialogBody,
@@ -24,7 +25,12 @@ import {
DialogHeader,
DialogTitle,
} from "@/components/ui/dialog";
-import { Field, FieldGroup, FieldLabel } from "@/components/ui/field";
+import {
+ Field,
+ FieldDescription,
+ FieldGroup,
+ FieldLabel,
+} from "@/components/ui/field";
import { Input } from "@/components/ui/input";
import {
Item,
@@ -54,6 +60,12 @@ import {
teamBotsQueryOptions,
unpublishTeamBotMutationOptions,
} from "@/lib/team-bots";
+import {
+ type TeamSummary,
+ teamListQueryOptions,
+ teamOfValue,
+ teamValue,
+} from "@/lib/teams/queries";
import { queryClient } from "@/query-client";
const list = (value: string) =>
@@ -62,13 +74,21 @@ const list = (value: string) =>
.map((part) => part.trim())
.filter(Boolean);
+/** Everybody in the organization, as an assignment carries it. */
+const EVERYONE = "*";
+const EVERYONE_WORDS = "Everyone in the organization";
+
/**
- * Who else can use this Bot. Its owner publishes it to the whole team or to named people and groups;
- * an administrator can also pin it at the top of a group's Bots lists. Each chat with a published
- * Bot is private to the person having it; its owner cannot read it.
+ * Who else can use this Bot. Its owner publishes it to everyone in the organization or to named
+ * people and teams; an admin can also pin it at the top of a team's Bots lists. Each conversation
+ * with a published Bot is private to the person having it; its owner cannot read it.
+ *
+ * A Bot published to directory groups before there were teams keeps them: they are shown, sent
+ * back unchanged, and no new one is typed. New grants go to teams.
*/
export function SharingSections({ agent }: { agent: AgentProfile }) {
const data = useQuery(teamBotsQueryOptions());
+ const teams = useQuery(teamListQueryOptions()).data?.teams;
const me = useQuery(currentUserQueryOptions()).data;
const unpublish = useMutation(unpublishTeamBotMutationOptions(queryClient));
const [copied, setCopied] = useState(false);
@@ -82,7 +102,7 @@ export function SharingSections({ agent }: { agent: AgentProfile }) {
);
}
const published = data.data.find((bot) => bot.botId === agent.id);
- // A Bot is its owner's to publish, and one missing from the Team Bots list isn't published yet.
+ // A Bot is its owner's to publish, and one missing from the published list isn't published yet.
const publishable = agent.mine && published === undefined;
return (
@@ -99,20 +119,23 @@ export function SharingSections({ agent }: { agent: AgentProfile }) {
-
-
- {published.audience === "team"
- ? "To the whole team"
- : `To ${[...(published.people ?? []), ...(published.groups ?? []).map((group) => `group ${group}`)].join(", ")}`}
+
+ {/*
+ * Every name is read, so the line wraps instead of being cut at one. An address
+ * has nowhere to break, so it may break anywhere before it runs under the button.
+ */}
+
+ {publishedTo(published, teams)}
{published.visibleToTeam
? "Each person's conversations with it are private."
- : "Teammates can't see it until it has a real name and a description."}
+ : "Other people can't see it until it has a real name and a description."}
{agent.mine ? (
-
+ // On a phone the names keep the row's width and the button goes under them.
+ unpublish.mutate(agent.id)}
@@ -155,7 +178,7 @@ export function SharingSections({ agent }: { agent: AgentProfile }) {
icon={IconShare}
title={
agent.visibility === "public"
- ? "Not published to the team"
+ ? "Not published to the organization"
: "Not published"
}
>
@@ -169,11 +192,11 @@ export function SharingSections({ agent }: { agent: AgentProfile }) {
{agent.mine && (published || publishable) ? (
- {/* More than one value — an audience, then people and groups — so a summary row and a
- dialog rather than a form on the page. */}
+ {/* More than one value (an audience, then people and teams), so a summary row and a
+ dialog, not a form on the page. */}
-
+
) : null}
>
);
}
+/** A team's name, by its id. One the list doesn't hold (deleted since, or not read yet) has none. */
+function teamName(
+ teams: readonly TeamSummary[] | undefined,
+ teamId: string,
+): string | undefined {
+ return teams?.find((team) => team.id === teamId)?.name;
+}
+
+/**
+ * Who a published Bot reaches, by name: people by their address, teams by their name, and the
+ * directory groups it was published to before there were teams. Teams whose names aren't known are
+ * counted, never shown by id.
+ */
+function publishedTo(
+ published: TeamBot,
+ teams: readonly TeamSummary[] | undefined,
+): string {
+ if (published.audience === "team")
+ return `To ${EVERYONE_WORDS.toLowerCase()}`;
+ const named: string[] = [];
+ let unnamed = 0;
+ for (const teamId of published.teams ?? []) {
+ const name = teamName(teams, teamId);
+ if (name) named.push(name);
+ else unnamed += 1;
+ }
+ const reached = [
+ ...(published.people ?? []),
+ ...named,
+ ...(unnamed > 0
+ ? [countLabel(unnamed, "other team", "other teams", "")]
+ : []),
+ ...(published.groups ?? []).map((group) => `group ${group}`),
+ ];
+ return reached.length ? `To ${reached.join(", ")}` : "To nobody yet";
+}
+
/** The current answer on the Audience row: who it is published to, as a count. */
function audienceSummary(current: TeamBot | undefined): string {
if (!current) return "Not published";
- if (current.audience === "team") return "The whole team";
+ if (current.audience === "team") return EVERYONE_WORDS;
const parts = [
countLabel(current.people?.length ?? 0, "person", "people", ""),
+ countLabel(current.teams?.length ?? 0, "team", "teams", ""),
countLabel(current.groups?.length ?? 0, "group", "groups", ""),
].filter(Boolean);
- return parts.length ? parts.join(", ") : "Specific people or groups";
+ return parts.length ? parts.join(", ") : AUDIENCES.people;
}
const AUDIENCES = {
- team: "The whole team",
- people: "Specific people or groups",
+ team: EVERYONE_WORDS,
+ people: "Specific people or teams",
} as const;
/**
- * Who a Bot is published to: the whole team, or named people and groups. Mounted only while open,
- * so each opening starts from the current answer rather than from an abandoned edit.
+ * Who a Bot is published to: everyone in the organization, or named people and teams. Mounted only
+ * while open, so each opening starts from the current answer and not from an abandoned edit.
*/
function PublishDialog({
botId,
@@ -245,11 +306,22 @@ function PublishDialog({
}) {
const formId = useId();
const publish = useMutation(publishTeamBotMutationOptions(queryClient));
+ const teams = useQuery(teamListQueryOptions());
const [audience, setAudience] = useState<"team" | "people">(
current?.audience ?? "team",
);
const [emails, setEmails] = useState((current?.people ?? []).join(", "));
- const [groups, setGroups] = useState((current?.groups ?? []).join(", "));
+ const [chosen, setChosen] = useState>(
+ () => new Set(current?.teams ?? []),
+ );
+ // Published to before there were teams. Kept as they are: shown, sent back, never typed.
+ const groups = current?.groups ?? [];
+ const toggle = (teamId: string) =>
+ setChosen((previous) => {
+ const next = new Set(previous);
+ if (!next.delete(teamId)) next.add(teamId);
+ return next;
+ });
return (
@@ -359,11 +484,28 @@ function PublishDialog({
);
}
+/** What an assignment is called: everyone, a team by its name, or a directory group by its own. */
+function assignmentName(
+ value: string,
+ teams: readonly TeamSummary[] | undefined,
+): string {
+ if (value === EVERYONE) return EVERYONE_WORDS;
+ const teamId = teamOfValue(value);
+ if (teamId === null) return `Group ${value}`;
+ return teamName(teams, teamId) ?? "A team that was deleted";
+}
+
/**
- * The groups an administrator has pinned this Bot for: one row each with a Remove, and a row that
- * opens a dialog to add one.
+ * Who an admin has pinned this Bot for: one row each with a Remove, and a row that opens a dialog
+ * to add one.
*/
-function Assignments({ bot }: { bot: TeamBot }) {
+function Assignments({
+ bot,
+ teams,
+}: {
+ bot: TeamBot;
+ teams: readonly TeamSummary[] | undefined;
+}) {
const remove = useMutation(assignTeamBotMutationOptions(queryClient));
const [assigning, setAssigning] = useState(false);
const assigned = bot.assignedGroups ?? [];
@@ -375,39 +517,42 @@ function Assignments({ bot }: { bot: TeamBot }) {
) : null}
{assigned.length === 0 ? (
-
+
) : null}
- {assigned.map((name) => (
-
-
-
-
-
-
- {name === "*" ? "Whole team" : name}
-
-
-
- remove.mutate({
- botId: bot.botId,
- group: name,
- remove: true,
- })
- }
- size="sm"
- variant="outline"
- >
- Remove
-
-
-
-
-
- ))}
+ {assigned.map((value) => {
+ const name = assignmentName(value, teams);
+ return (
+
+
+
+ {value === EVERYONE ? : }
+
+
+ {name}
+
+
+
+ remove.mutate({
+ botId: bot.botId,
+ group: value,
+ remove: true,
+ })
+ }
+ size="sm"
+ variant="outline"
+ >
+ Remove
+
+
+
+
+
+ );
+ })}
setAssigning(true)} type="button" />}
size="sm"
@@ -416,7 +561,7 @@ function Assignments({ bot }: { bot: TeamBot }) {
- Assign to a group
+ Assign to a team or everyone
@@ -424,24 +569,43 @@ function Assignments({ bot }: { bot: TeamBot }) {
{assigning ? (
- setAssigning(false)} />
+ setAssigning(false)}
+ teams={teams ?? []}
+ />
) : null}
>
);
}
-/** One group to pin this Bot for, or * for the whole team. */
-function AssignDialog({ bot, onClose }: { bot: TeamBot; onClose: () => void }) {
+/** One team to pin this Bot for, or everyone in the organization. What it already has is left out. */
+function AssignDialog({
+ bot,
+ teams,
+ onClose,
+}: {
+ bot: TeamBot;
+ teams: readonly TeamSummary[];
+ onClose: () => void;
+}) {
const formId = useId();
const assign = useMutation(assignTeamBotMutationOptions(queryClient));
- const [group, setGroup] = useState("");
+ const taken = new Set(bot.assignedGroups ?? []);
+ const choices: Record = Object.fromEntries(
+ [
+ [EVERYONE, EVERYONE_WORDS] as const,
+ ...teams.map((team) => [teamValue(team.id), team.name] as const),
+ ].filter(([value]) => !taken.has(value)),
+ );
+ const [group, setGroup] = useState(null);
return (
+ {/*
+ * Which teams may give it to their own Bots without asking. A set of teams, so a
+ * summary and a dialog. No icon, as no other row of this card has one.
+ */}
+
>
) : null}
@@ -888,7 +914,7 @@ export function PluginPage({
? `${title} answers without an account, so ${personal ? "your Bots use" : "Bots use"} it as it is. Add a key only if ${title} gives you one.`
: personal
? `What OpenBot sends to ${title}. Your Bots all use it.`
- : `What ${paths.deploymentName} sends to the vendor. One credential for everybody.`
+ : "What OpenBot sends to the vendor. One credential for everybody in this organization."
}
title="Connection"
>
@@ -1105,9 +1131,9 @@ export function PluginPage({
*/
- Team account
+ Shared account
- {`${title} connects only as one shared account. Make it shared above, then connect the team account here and give it to Bots.`}
+ {`${title} connects only as one shared account. Make it shared above, then connect that account here and give it to Bots.`}
@@ -1116,9 +1142,9 @@ export function PluginPage({
account={brokeredAccount}
edition={paths.edition}
connectedDescription={`Connected${sharedConnection?.displayName ? ` as ${sharedConnection.displayName}` : ""}${sharedConnection?.connectedBy ? ` by ${sharedConnection.connectedBy}` : ""}. Every Bot with these tools acts as this account.`}
- disconnectedDescription="No team account is connected. Bots with these tools are refused."
- heading="Team account"
- notice="Sign in as the team account, not your own."
+ disconnectedDescription="No shared account is connected. Bots with these tools are refused."
+ heading="Shared account"
+ notice="Sign in as the shared account, not your own."
provider={provider}
title={title}
/>
@@ -1555,10 +1581,10 @@ export function PluginPage({
{dialog === "client"
- ? `From the vendor's console. The secret is saved in ${paths.deploymentName}'s vault and never shown again.`
+ ? `From the vendor's console. The secret is saved in ${vaultOwner}'s vault and never shown again.`
: dialog === "instance"
? "Your own hostname with this vendor. It is checked against the vendor's pattern before it is saved."
- : `Saved in ${paths.deploymentName}'s vault and never shown again.`}
+ : `Saved in ${vaultOwner}'s vault and never shown again.`}
diff --git a/app/src/components/manage/plugin-tool-page.tsx b/app/src/components/manage/plugin-tool-page.tsx
index 9d62280a90..867006e527 100644
--- a/app/src/components/manage/plugin-tool-page.tsx
+++ b/app/src/components/manage/plugin-tool-page.tsx
@@ -17,6 +17,7 @@ import {
import { Separator } from "@/components/ui/separator";
import { Switch } from "@/components/ui/switch";
import { grantRoster } from "@/lib/agents/grant-roster";
+import { useBotListScope } from "@/lib/agents/list-scope";
import { agentListQueryOptions } from "@/lib/agents/queries";
import { ALWAYS_ON_APP } from "@/lib/connections/rows";
import { useManagePaths } from "@/lib/manage-paths";
@@ -48,9 +49,11 @@ export function PluginToolPage({
const queryClient = useQueryClient();
const plugins = useQuery(appsQueryOptions());
const setup = useQuery(appSetupQueryOptions());
- const { data: agents } = useQuery(agentListQueryOptions());
+ // Under Admin, every Bot in the organization (lib/agents/list-scope.tsx).
+ const scope = useBotListScope();
+ const { data: agents } = useQuery(agentListQueryOptions(false, scope));
/* The ones this person has hidden, so a grant one of them holds still has its switch here. */
- const { data: hiddenAgents } = useQuery(agentListQueryOptions(true));
+ const { data: hiddenAgents } = useQuery(agentListQueryOptions(true, scope));
/*
* Whether a call from this Bot could be authenticated at all.
*
@@ -95,7 +98,7 @@ export function PluginToolPage({
return (
- Couldn't load plugins. Reload the page.
+ Couldn't load plugins. Try again in a moment.
- {opens ? (
- (onSelect ? onSelect() : setOpened(!opened))}
- type="button"
- >
+ {/*
+ * The words and the buttons share a line while the words keep room to be read (20rem), and
+ * the buttons go under the words, lined up with them, where they don't. On a phone or in a
+ * narrow window, three buttons beside the words squeezed them to a word or two per line.
+ */}
+
+ {shownMeta.map((piece, index) => (
+ // biome-ignore lint/suspicious/noArrayIndexKey: the pieces are fixed per row.
+
+ {index > 0 ? · : null}
+ {piece}
+
+ ))}
+
+ ) : null}
+
+ {actions ? (
+
+ {actions}
) : null}
- {actions ? (
-
{actions}
- ) : null}
{open && more ?
{more}
: null}
diff --git a/app/src/components/needs-you/board.tsx b/app/src/components/needs-you/board.tsx
index c5bb7a5af5..36ab7b2889 100644
--- a/app/src/components/needs-you/board.tsx
+++ b/app/src/components/needs-you/board.tsx
@@ -2,7 +2,10 @@ import { IconChevronDown } from "@tabler/icons-react";
import { useQuery } from "@tanstack/react-query";
import { Fragment, type ReactNode, useState } from "react";
import { BotOrb } from "@/components/agents/bot-orb";
-import { useWaitingByBot } from "@/components/approvals/waiting";
+import {
+ useHeldAnswers,
+ useWaitingByBot,
+} from "@/components/approvals/waiting";
import { PageSection } from "@/components/layout/page-shell";
import { SuggestionRow } from "@/components/suggestions/suggestion-row";
import { TaskBoardRow } from "@/components/tasks/task-row";
@@ -15,7 +18,9 @@ import {
} from "@/lib/proactive";
import type { ReadFailure } from "@/lib/read-failure";
import { relativeTime } from "@/lib/relative-time";
+import { countsAsWaiting, heldByTaskOf } from "@/lib/tasks/groups";
import { useNeedsYou } from "./needs-you";
+import { StalledHandoffBoardRow, useStalledHandoffs } from "./stalled-handoffs";
/** How many of one Bot's finds show before the rest open in place. */
const FINDS_SHOWN = 3;
@@ -35,18 +40,52 @@ const FINDS_SHOWN = 3;
export function NeedsYouBoard({ agentId }: { agentId?: string }) {
const agents = useQuery(agentListQueryOptions());
const settings = useQuery(proactiveSettingsQueryOptions());
- const waiting = useWaitingByBot(agentId);
const list = useNeedsYou(agentId);
+ // A question or an action waiting in a task's own conversation is that task waiting: one row.
+ const waiting = useWaitingByBot(
+ agentId,
+ heldByTaskOf([...list.tasks, ...list.done]),
+ );
+
+ const stalledHandoffs = useStalledHandoffs(agentId);
+ // A task waiting on something in its thread is answered on its own row.
+ const heldAnswer = useHeldAnswers();
const blocked = new Map(waiting.byBot);
+ // Questions and actions each wait on the person; a task does when the badge counts it.
+ let waitingCount = [...waiting.byBot.values()].reduce(
+ (total, group) => total + group.rows.length,
+ 0,
+ );
for (const listed of list.tasks) {
+ if (countsAsWaiting(listed)) waitingCount += 1;
const group = blocked.get(listed.task.agentId) ?? { rows: [], times: [] };
group.rows.push(
- ,
+ ,
);
- group.times.push(listed.task.updatedAt);
+ // Only what waits on the person says how long it has waited.
+ if (countsAsWaiting(listed)) group.times.push(listed.task.updatedAt);
blocked.set(listed.task.agentId, group);
}
+ // A hand-off that ran out of tries waits on the person too, and the badge counts it.
+ for (const stalled of stalledHandoffs) {
+ waitingCount += 1;
+ const group = blocked.get(stalled.botId) ?? { rows: [], times: [] };
+ group.rows.push(
+ ,
+ );
+ group.times.push(stalled.item.at);
+ blocked.set(stalled.botId, group);
+ }
const found = new Map();
for (const item of list.items)
found.set(item.botId, [...(found.get(item.botId) ?? []), item]);
@@ -77,10 +116,6 @@ export function NeedsYouBoard({ agentId }: { agentId?: string }) {
const bot = (id: string) => agents.data?.find((agent) => agent.id === id);
const settingOf = (id: string | null | undefined) =>
id ? settings.data?.find((setting) => setting.id === id) : undefined;
- const waitingCount = [...blocked.values()].reduce(
- (total, group) => total + group.rows.length,
- 0,
- );
const foundCount = list.items.length;
return (
@@ -106,17 +141,21 @@ export function NeedsYouBoard({ agentId }: { agentId?: string }) {
) : null}
{blocked.size ? (
-
+
{[...blocked].map(([botId, group]) => (
- Date.parse(at) < Date.parse(first) ? at : first,
- ),
- )}`}
+ note={
+ group.times.length
+ ? `waiting since ${relativeTime(
+ group.times.reduce((first, at) =>
+ Date.parse(at) < Date.parse(first) ? at : first,
+ ),
+ )}`
+ : "nothing waiting on you"
+ }
>
{group.rows}
diff --git a/app/src/components/needs-you/needs-you.tsx b/app/src/components/needs-you/needs-you.tsx
index b40c1c11c2..96d1a4608a 100644
--- a/app/src/components/needs-you/needs-you.tsx
+++ b/app/src/components/needs-you/needs-you.tsx
@@ -159,7 +159,14 @@ export function DoneTasks({ done }: { done: ListedTask[] }) {
return (
setOpen(!open)} size="sm" variant="ghost">
+ // Short on screen; to a screen reader it says which list it opens, beside Hidden's own Show.
+ setOpen(!open)}
+ size="sm"
+ variant="ghost"
+ >
{open ? "Hide" : "Show"}
}
diff --git a/app/src/components/needs-you/stalled-handoffs.tsx b/app/src/components/needs-you/stalled-handoffs.tsx
new file mode 100644
index 0000000000..4abebeecbb
--- /dev/null
+++ b/app/src/components/needs-you/stalled-handoffs.tsx
@@ -0,0 +1,89 @@
+import { IconArrowsExchange } from "@tabler/icons-react";
+import { useQueries, useQuery } from "@tanstack/react-query";
+import { Link } from "@tanstack/react-router";
+import { BoardRow } from "@/components/needs-you/board-row";
+import { Button } from "@/components/ui/button";
+import {
+ type ActivityItem,
+ botActivityQueryOptions,
+ botAttentionQueryOptions,
+} from "@/lib/bot-lifecycle/queries";
+import { relativeTime } from "@/lib/relative-time";
+
+/** A hand-off a Bot asked for that ran out of tries: only the person can pick it up. */
+export type StalledHandoff = { botId: string; item: ActivityItem };
+
+/**
+ * Every stalled hand-off the Bots badge counts, as rows to list: the badge counts them per Bot
+ * (`handoffs` on what the server says each Bot waits on), and each one is read from that Bot's own
+ * Activity, where it is the item that needs the person. Given a Bot, only that Bot's. Read only for
+ * a Bot the badge counts one for, so a quiet day reads nothing.
+ */
+export function useStalledHandoffs(agentId?: string): StalledHandoff[] {
+ const attention = useQuery(botAttentionQueryOptions());
+ const asking = (attention.data ?? [])
+ .filter(
+ (bot) =>
+ bot.handoffs > 0 && (agentId === undefined || bot.botId === agentId),
+ )
+ .map((bot) => bot.botId);
+ const reads = useQueries({
+ queries: asking.map((botId) => botActivityQueryOptions(botId)),
+ });
+ const seen = new Set();
+ const stalled: StalledHandoff[] = [];
+ asking.forEach((botId, at) => {
+ for (const item of reads[at]?.data?.inProgress ?? []) {
+ if (item.kind !== "handoff" || !item.needsYou || seen.has(item.id))
+ continue;
+ seen.add(item.id);
+ stalled.push({ botId, item });
+ }
+ });
+ return stalled;
+}
+
+/** A stalled hand-off on the Needs you board, in the board's one row shape, with Open into it. */
+export function StalledHandoffBoardRow({
+ stalled,
+}: {
+ stalled: StalledHandoff;
+}) {
+ const { item } = stalled;
+ const { channelId } = item;
+ return (
+ }
+ size="sm"
+ >
+ Open
+
+ ) : (
+
+ }
+ size="sm"
+ >
+ Open
+
+ )
+ }
+ detail={item.detail}
+ icon={}
+ meta={[
+ Stalled hand-off,
+ {relativeTime(item.at)},
+ ]}
+ state="stalled"
+ title={item.title}
+ waiting
+ />
+ );
+}
diff --git a/app/src/components/organizations/invitations-page.tsx b/app/src/components/organizations/invitations-page.tsx
new file mode 100644
index 0000000000..7af6e4090d
--- /dev/null
+++ b/app/src/components/organizations/invitations-page.tsx
@@ -0,0 +1,210 @@
+import { IconBuilding, IconMail, IconMailOff } from "@tabler/icons-react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { Fragment, useState } from "react";
+import { PageEmpty, PageRows, PageShell } from "@/components/layout/page-shell";
+import { Button } from "@/components/ui/button";
+import {
+ Item,
+ ItemActions,
+ ItemContent,
+ ItemDescription,
+ ItemMedia,
+ ItemTitle,
+} from "@/components/ui/item";
+import { Separator } from "@/components/ui/separator";
+import { useCurrentOrganizationId } from "@/lib/organizations/current";
+import {
+ acceptInvitationMutationOptions,
+ declineInvitationMutationOptions,
+} from "@/lib/organizations/mutations";
+import {
+ type ReceivedInvitation,
+ receivedInvitationQueryOptions,
+ receivedInvitationsQueryOptions,
+} from "@/lib/organizations/queries";
+import { receivedInvitationLine } from "@/lib/organizations/words";
+import { queryClient } from "@/query-client";
+import { useSwitchOrganization } from "./use-switch-organization";
+
+/**
+ * One invitation as the person it was sent to sees it, in whatever state it is in.
+ *
+ * Waiting, it offers Accept and Decline. Accepting does not move the person: they keep working
+ * where they were, and the row then offers the switch. Expired, declined or canceled, it says so
+ * and offers nothing. A refusal is drawn under the row in the server's own sentence while the
+ * invitation still waits; one that expired or was canceled meanwhile is said by the row itself.
+ */
+export function InvitationRow({
+ invitation,
+ onAccepted,
+}: {
+ invitation: ReceivedInvitation;
+ /** Told when the person has joined, for a list the accepted invitation then leaves. */
+ onAccepted?: (invitation: ReceivedInvitation) => void;
+}) {
+ const accepting = acceptInvitationMutationOptions(queryClient);
+ const accept = useMutation({
+ ...accepting,
+ /*
+ * Told before the lists are read again, not from the button's own callback: reading them again
+ * takes an accepted invitation out of the list, and this row with it, and a row that has gone
+ * hears nothing. Declaring an `onSuccess` over the spread replaces the factory's, so it is
+ * called here, by hand.
+ */
+ onSuccess: async (...args) => {
+ onAccepted?.({ ...invitation, status: "accepted" });
+ await accepting.onSuccess?.(...args);
+ },
+ });
+ const decline = useMutation(declineInvitationMutationOptions(queryClient));
+ const switching = useSwitchOrganization();
+ const current = useCurrentOrganizationId();
+ const busy = accept.isPending || decline.isPending;
+ /*
+ * Only while the invitation still waits. A refusal that changed it (it expired or was canceled
+ * meanwhile) has the row read again, and the row's own line then says what happened, so the
+ * refusal under it would say the same thing twice in two wordings.
+ */
+ const failure =
+ invitation.status === "pending" ? (accept.error ?? decline.error) : null;
+ const { name } = invitation.organization;
+
+ return (
+ <>
+
+
+
+
+
+ {name}
+
+ {receivedInvitationLine(invitation)}
+
+
+ {invitation.status === "pending" ? (
+
+ {
+ accept.reset();
+ decline.mutate(invitation.id);
+ }}
+ size="sm"
+ variant="outline"
+ >
+ {decline.isPending ? "Declining…" : "Decline"}
+
+ {
+ decline.reset();
+ accept.mutate(invitation.id);
+ }}
+ size="sm"
+ >
+ {accept.isPending ? "Accepting…" : "Accept"}
+
+
+ ) : invitation.status === "accepted" &&
+ invitation.organization.id !== current ? (
+
+ switching.run(invitation.organization.id)}
+ size="sm"
+ >
+ Switch to {name}
+
+
+ ) : null}
+
+ {failure ? (
+
+ {failure.message}
+
+ ) : null}
+ >
+ );
+}
+
+/**
+ * The invitations waiting for the person, whichever organization they are working in.
+ *
+ * One they accept leaves the server's list, so it is kept here as accepted until they leave the
+ * page: the row is where the switch to the organization they just joined is offered.
+ */
+export function InvitationsPage() {
+ const invitations = useQuery(receivedInvitationsQueryOptions());
+ const [accepted, setAccepted] = useState([]);
+ const listed = invitations.data ?? [];
+ const rows = [
+ ...accepted.filter((one) => !listed.some((other) => other.id === one.id)),
+ ...listed,
+ ];
+
+ return (
+
+ {invitations.isPending ? null : invitations.error ? (
+
+ {invitations.error.message}
+
+ ) : rows.length === 0 ? (
+
+ When somebody invites you to an organization, it shows here.
+
+ ) : (
+
+ {rows.map((invitation, index) => (
+
+
+ setAccepted((before) => [
+ joined,
+ ...before.filter((one) => one.id !== joined.id),
+ ])
+ }
+ />
+ {index !== rows.length - 1 && }
+
+ ))}
+
+ )}
+
+ );
+}
+
+/**
+ * The page an invitation's link opens: that one invitation, in whatever state it is in. One the
+ * server does not find for this person is said so, with the one thing to check.
+ */
+export function InvitationPage({ invitationId }: { invitationId: string }) {
+ const invitation = useQuery(receivedInvitationQueryOptions(invitationId));
+
+ return (
+
+ {invitation.isPending ? null : invitation.error ? (
+
+ {invitation.error.message}
+
+ ) : invitation.data === null ? (
+
+ Check that you're signed in with the address it was sent to.
+
+ ) : (
+
+
+
+ )}
+
+ );
+}
diff --git a/app/src/components/organizations/new-organization-dialog.tsx b/app/src/components/organizations/new-organization-dialog.tsx
index f2d3683f59..8a07724295 100644
--- a/app/src/components/organizations/new-organization-dialog.tsx
+++ b/app/src/components/organizations/new-organization-dialog.tsx
@@ -92,8 +92,8 @@ function NewOrganizationForm() {
New organization
- A new organization starts with no Bots and no conversations. You
- switch to it as soon as it's created.
+ A new organization starts with OpenBot's starter Bots and skills,
+ and no conversations. You switch to it as soon as it's created.
diff --git a/app/src/components/organizations/organization-menu.tsx b/app/src/components/organizations/organization-menu.tsx
index 5407e2f785..3412ea5940 100644
--- a/app/src/components/organizations/organization-menu.tsx
+++ b/app/src/components/organizations/organization-menu.tsx
@@ -1,4 +1,11 @@
-import { IconBuilding, IconPlus } from "@tabler/icons-react";
+import {
+ IconBuilding,
+ IconMail,
+ IconPlus,
+ IconSettings,
+ IconUserCircle,
+} from "@tabler/icons-react";
+import { Link } from "@tanstack/react-router";
import {
DropdownMenuGroup,
DropdownMenuItem,
@@ -7,24 +14,41 @@ import {
DropdownMenuRadioItem,
DropdownMenuSeparator,
} from "@/components/ui/dropdown-menu";
-import type { OwnOrganizations } from "@/lib/organizations/queries";
+import {
+ Tooltip,
+ TooltipContent,
+ TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { useAnythingCut } from "@/hooks/use-anything-cut";
+import type {
+ OrganizationSummary,
+ OwnOrganizations,
+} from "@/lib/organizations/queries";
import { cn } from "@/lib/utils";
/**
* The person's organizations at the top of the account menu: the one they are working in checked,
- * the others one click away, and New organization for somebody who may create one.
+ * the others one click away, its settings, the invitations waiting for their answer, and New
+ * organization for somebody who may create one.
*
- * Drawn only when there is something to switch to or create (`useOrganizationChoices`), so for
+ * Drawn only where OpenBot lists the person's organizations (`useOrganizationChoices`), so for
* everybody else the menu is the one it always was. The rows take the menu's own item spacing from
- * `itemClassName`, and a long name is cut short where the menu is as narrow as the sidebar.
+ * `itemClassName`. The account menu grows to a long name (`accountMenuClassName`), and a name too
+ * long even for that reads whole in a tooltip.
*/
export function OrganizationMenuItems({
choices,
+ invitationsWaiting,
itemClassName,
onNew,
switching,
}: {
choices: OwnOrganizations;
+ /**
+ * How many invitations wait for the person's answer. The entry is drawn when some do, and without
+ * a count when they could not be read (null), so the page that says why is still one click away.
+ */
+ invitationsWaiting: number | null;
itemClassName: string;
/** Open the New organization dialog, which lives outside the menu so it outlasts it. */
onNew: () => void;
@@ -45,19 +69,43 @@ export function OrganizationMenuItems({
value={choices.currentId}
>
{choices.organizations.map((organization) => (
-
-
- {organization.name}
-
+ organization={organization}
+ />
))}
+ {choices.organizations.length > 0 ? (
+ }
+ >
+
+ Organization settings
+
+ ) : null}
+ {invitationsWaiting === null || invitationsWaiting > 0 ? (
+ }
+ >
+
+ Invitations
+ {invitationsWaiting === null ? null : (
+
+ {invitationsWaiting}
+ , {invitationsWaiting} waiting
+
+ )}
+
+ ) : null}
{choices.canCreate ? (
@@ -69,3 +117,46 @@ export function OrganizationMenuItems({
>
);
}
+
+/**
+ * One organization to switch to. A name the menu still cuts short reads whole in a tooltip, on
+ * hover and when the keyboard highlights the row (the menu highlights a row by focusing it), as the
+ * account row's own tooltip does. Cutting is only paint: the row's name for assistive technology is
+ * always the whole name.
+ */
+function OrganizationRow({
+ className,
+ disabled,
+ organization,
+}: {
+ className: string;
+ disabled: boolean;
+ organization: OrganizationSummary;
+}) {
+ const { ref, cut } = useAnythingCut();
+ return (
+
+
+ }
+ >
+ {/* The person's own organization carries a person's mark; one they share, a building. */}
+ {organization.personal ? : }
+ {organization.name}
+
+
+ {organization.name}
+
+
+ );
+}
diff --git a/app/src/components/organizations/organization-settings-page.tsx b/app/src/components/organizations/organization-settings-page.tsx
new file mode 100644
index 0000000000..bb1db8d65f
--- /dev/null
+++ b/app/src/components/organizations/organization-settings-page.tsx
@@ -0,0 +1,653 @@
+import {
+ IconBuilding,
+ IconChevronDown,
+ IconChevronRight,
+} from "@tabler/icons-react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { useNavigate } from "@tanstack/react-router";
+import { Fragment, useEffect, useId, useState } from "react";
+import {
+ PageRows,
+ PageSection,
+ PageShell,
+} from "@/components/layout/page-shell";
+import { Button } from "@/components/ui/button";
+import {
+ Dialog,
+ DialogBody,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+} from "@/components/ui/dialog";
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { Field, FieldLabel } from "@/components/ui/field";
+import { Input } from "@/components/ui/input";
+import {
+ Item,
+ ItemActions,
+ ItemContent,
+ ItemDescription,
+ ItemMedia,
+ ItemTitle,
+} from "@/components/ui/item";
+import { Separator } from "@/components/ui/separator";
+import { currentUserQueryOptions } from "@/lib/auth/queries";
+import { isOrganizationAdmin } from "@/lib/auth/roles";
+import {
+ changeMemberRoleMutationOptions,
+ leaveOrganizationMutationOptions,
+ removeOrganizationMemberMutationOptions,
+ renameOrganizationMutationOptions,
+} from "@/lib/organizations/mutations";
+import {
+ type OrganizationMemberSummary,
+ type OrganizationSummary,
+ organizationMembersQueryOptions,
+ useOrganizationChoices,
+} from "@/lib/organizations/queries";
+import {
+ initialsOf,
+ memberControl,
+ personName,
+ roleChangeQuestion,
+ roleInSentence,
+ roleName,
+} from "@/lib/organizations/words";
+import { queryClient } from "@/query-client";
+import { SentInvitationsSection } from "./sent-invitations-section";
+
+/** The API's cap on an organization's name, so the field stops where the server does. */
+const MAX_NAME_LENGTH = 100;
+
+/**
+ * The organization the person is working in: its name, who is in it, and the invitations it sent.
+ *
+ * What a row offers follows the person's role in this organization, which is the server's verdict
+ * from the list of their organizations: an owner or an admin renames it, invites people and removes
+ * members; a member reads the name and the members, and may leave. The server decides each of them
+ * again and its refusal is drawn in its own sentence.
+ */
+export function OrganizationSettingsPage() {
+ const choices = useOrganizationChoices();
+ const organization = choices?.organizations.find(
+ (one) => one.id === choices.currentId,
+ );
+ // Nothing until the list has answered. Where OpenBot lists none, the route never opens this page.
+ if (!organization) return null;
+ const canManage = isOrganizationAdmin(organization.role);
+
+ return (
+
+
+
+
+
+
+
+ {canManage ? (
+
+ ) : null}
+
+ );
+}
+
+/**
+ * The organization's name. A summary that opens a dialog for somebody who may rename it, and the
+ * name with nothing to click for a member.
+ */
+function NameRow({
+ canManage,
+ organization,
+}: {
+ canManage: boolean;
+ organization: OrganizationSummary;
+}) {
+ const [open, setOpen] = useState(false);
+ const media = (
+
+
+
+ );
+ if (!canManage) {
+ return (
+
+ {media}
+
+ Name
+
+
+
+ {organization.name}
+
+
+
+ );
+ }
+ return (
+ <>
+ setOpen(true)} type="button" />}
+ size="sm"
+ >
+ {media}
+
+ Name
+ {organization.name}
+
+
+
+
+
+
+ >
+ );
+}
+
+function RenameOrganizationDialog({
+ onOpenChange,
+ open,
+ organization,
+}: {
+ onOpenChange: (open: boolean) => void;
+ open: boolean;
+ organization: OrganizationSummary;
+}) {
+ const formId = useId();
+ const rename = useMutation(renameOrganizationMutationOptions(queryClient));
+ const { reset } = rename;
+ const [name, setName] = useState(organization.name);
+
+ // Each opening starts from the name it has, and a refusal from the last one is not news about this one.
+ useEffect(() => {
+ if (open) {
+ setName(organization.name);
+ reset();
+ }
+ }, [open, organization.name, reset]);
+
+ const save = async () => {
+ try {
+ await rename.mutateAsync({
+ organizationId: organization.id,
+ name: name.trim(),
+ });
+ } catch {
+ // The error is on the mutation and drawn below; staying open says "not done".
+ return;
+ }
+ onOpenChange(false);
+ };
+
+ return (
+
+ );
+}
+
+/** A person's picture, or their initials on the tint the account row uses. */
+function PersonAvatar({ person }: { person: OrganizationMemberSummary }) {
+ return (
+
+ );
+}
+
+/** A member and the role they are about to be given. */
+type RoleChange = {
+ member: OrganizationMemberSummary;
+ role: OrganizationMemberSummary["role"];
+};
+
+/**
+ * Who is in the organization, with each person's role, and what their row offers: a Role menu
+ * listing the roles the server says the person looking may give them (`assignableRoles`), and
+ * Remove or Leave where the membership can end (`removable`).
+ */
+function MembersSection({
+ organization,
+}: {
+ organization: OrganizationSummary;
+}) {
+ const members = useQuery(organizationMembersQueryOptions(organization.id));
+ const me = useQuery(currentUserQueryOptions()).data;
+ const changeRole = useMutation(changeMemberRoleMutationOptions(queryClient));
+ // Kept while its dialog closes, so the question does not lose its name on the way out.
+ const [removing, setRemoving] = useState(
+ null,
+ );
+ const [removeOpen, setRemoveOpen] = useState(false);
+ const [leaveOpen, setLeaveOpen] = useState(false);
+ const [changing, setChanging] = useState(null);
+ const [changeOpen, setChangeOpen] = useState(false);
+ const viewer = { id: me?.id, role: organization.role };
+
+ // Making somebody an owner, and stepping down, are asked about first. The rest apply at once.
+ const giveRole = (change: RoleChange) => {
+ changeRole.reset();
+ if (roleChangeQuestion(change.member, change.role, me?.id)) {
+ setChanging(change);
+ setChangeOpen(true);
+ return;
+ }
+ changeRole.mutate({
+ organizationId: organization.id,
+ personId: change.member.id,
+ role: change.role,
+ });
+ };
+
+ return (
+
+ {members.isPending ? null : members.error ? (
+
- Couldn't load access requests. Reload the page.
+ Couldn't load access requests. Try again in a moment.
);
diff --git a/app/src/components/plugins/account-mode-dialog.tsx b/app/src/components/plugins/account-mode-dialog.tsx
index 839eda8e66..05249ea708 100644
--- a/app/src/components/plugins/account-mode-dialog.tsx
+++ b/app/src/components/plugins/account-mode-dialog.tsx
@@ -13,7 +13,8 @@ import {
accountModePreview,
setAccountModeMutationOptions,
} from "@/lib/apps/mutations";
-import { describeApproval } from "@/lib/plugins/shared-use";
+import { approvalNamesTeam, describeApproval } from "@/lib/plugins/shared-use";
+import { teamListQueryOptions } from "@/lib/teams/queries";
/**
* The one moment an administrator decides between people's own accounts and one shared account.
@@ -50,6 +51,13 @@ export function AccountModeDialog({
queryFn: () => accountModePreview(serverId, target),
enabled: open,
});
+ // A Bot's approval keeps a team's id; its name comes from the organization's teams, read once.
+ const teams = useQuery({
+ ...teamListQueryOptions(),
+ enabled:
+ open &&
+ (preview.data?.bots ?? []).some((bot) => approvalNamesTeam(bot.exposure)),
+ }).data?.teams;
const change = useMutation({
...setAccountModeMutationOptions(queryClient),
onSuccess: () => onOpenChange(false),
@@ -89,7 +97,7 @@ export function AccountModeDialog({
{names[bot.botId] ?? bot.botId}
- : {describeApproval(bot.exposure)}
+ : {describeApproval(bot.exposure, teams)}
))}
diff --git a/app/src/components/plugins/app-access-action.tsx b/app/src/components/plugins/app-access-action.tsx
index 8e449ca538..9b5057161d 100644
--- a/app/src/components/plugins/app-access-action.tsx
+++ b/app/src/components/plugins/app-access-action.tsx
@@ -266,8 +266,11 @@ function AdminAction({
access.state !== "shared_not_connected"
? ["Set it up", `Set up ${name}`]
: access.requestKind
- ? ["Connect the team account", `Connect the team ${name} account`]
- : ["Reconnect the team account", `Reconnect the team ${name} account`];
+ ? ["Connect the shared account", `Connect the shared ${name} account`]
+ : [
+ "Reconnect the shared account",
+ `Reconnect the shared ${name} account`,
+ ];
/*
* A broker with no key is set up on its directory, which is a page of its own in the personal
* edition. There `/connections/composio` would read as an app called "composio" and say there is
diff --git a/app/src/components/plugins/broker-directory.tsx b/app/src/components/plugins/broker-directory.tsx
index 49cda596cb..b3255ee019 100644
--- a/app/src/components/plugins/broker-directory.tsx
+++ b/app/src/components/plugins/broker-directory.tsx
@@ -12,7 +12,7 @@ import {
type ConnectInNewTab,
useConnectInNewTab,
} from "@/components/plugins/connect-in-new-tab";
-import { AppInitial } from "@/components/plugins/plugin-logo";
+import { AppInitial, LOGO_TILE } from "@/components/plugins/plugin-logo";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import {
@@ -33,6 +33,11 @@ import {
directorySlug,
} from "@/lib/apps/queries";
import { useManagePaths } from "@/lib/manage-paths";
+import {
+ type DirectoryAppState,
+ directoryAppState,
+ directoryConnect,
+} from "@/lib/plugins/directory-state";
import {
consentBreadth,
coverageWarning,
@@ -46,11 +51,6 @@ import {
type PluginsProvider,
providerVocabulary,
} from "@/lib/plugins/provider-vocabulary";
-import {
- type DirectoryAppState,
- directoryAppState,
- directoryConnect,
-} from "@/lib/plugins/directory-state";
import { connectionsQueryOptions } from "@/lib/plugins/queries";
/**
@@ -318,7 +318,7 @@ export function BrokerDirectory({ provider }: { provider: PluginsProvider }) {
>
{query
? `No app matches "${query}".`
- : "No apps to show yet. Reload the page to try again."}
+ : "No apps to show yet. Try again in a moment."}
) : (
<>
@@ -346,7 +346,10 @@ export function BrokerDirectory({ provider }: { provider: PluginsProvider }) {
>
{/* The vendor's own mark where the broker supplies one, and its initial where it
does not, so a list of third parties still has a fixed left edge. */}
-
+
{entry.logo ? (
) : (
diff --git a/app/src/components/plugins/brokered-account-row.tsx b/app/src/components/plugins/brokered-account-row.tsx
index 73090c488a..5fb1c441d7 100644
--- a/app/src/components/plugins/brokered-account-row.tsx
+++ b/app/src/components/plugins/brokered-account-row.tsx
@@ -484,7 +484,7 @@ export function useBrokeredAccount(input: {
*/
if (start === null) {
report(
- "This app connects with a key, not a sign-in page, so nothing was connected. Reload the page and press Connect again.",
+ "This app connects with a key, not a sign-in page, so nothing was connected. Open this app again from Connections and press Connect.",
);
return;
}
@@ -650,7 +650,7 @@ export function useBrokeredAccount(input: {
}
if (start === null) {
report(
- "This app connects with a key, not a sign-in page, so nothing was connected. Reload the page and press Connect again.",
+ "This app connects with a key, not a sign-in page, so nothing was connected. Open this app again from Connections and press Connect.",
);
return;
}
diff --git a/app/src/components/plugins/plugin-logo.tsx b/app/src/components/plugins/plugin-logo.tsx
index d2c279a25f..9a27a1a425 100644
--- a/app/src/components/plugins/plugin-logo.tsx
+++ b/app/src/components/plugins/plugin-logo.tsx
@@ -1,5 +1,14 @@
import { IconPlug } from "@tabler/icons-react";
import { useState } from "react";
+import { cn } from "@/lib/utils";
+
+/**
+ * ON A WHITE TILE IN DARK MODE, BECAUSE SOME MARKS DISAPPEAR WITHOUT ONE. GitHub's mark is black,
+ * and on the dark page it all but vanished. A vendor's artwork is never recoloured, so dark mode
+ * gives every mark a white tile instead: the same rule the framework marks follow
+ * (`agents/harness-mark.tsx`). Every mark reads on white.
+ */
+export const LOGO_TILE = "rounded-sm dark:bg-white dark:p-0.5";
/**
* An app's logo, or its initial where it has none.
@@ -24,7 +33,7 @@ export function PluginLogo({
setFailedUrl(logo)}
diff --git a/app/src/components/plugins/shared-approval-fields.tsx b/app/src/components/plugins/shared-approval-fields.tsx
index e0d85b7af5..bfebecb647 100644
--- a/app/src/components/plugins/shared-approval-fields.tsx
+++ b/app/src/components/plugins/shared-approval-fields.tsx
@@ -1,7 +1,23 @@
+import { IconBuildingBank, IconUsersGroup } from "@tabler/icons-react";
+import { useQuery } from "@tanstack/react-query";
+import { Fragment, type ReactNode, useId } from "react";
+import { Button } from "@/components/ui/button";
+import { Checkbox } from "@/components/ui/checkbox";
import {
- describeApproval,
+ Item,
+ ItemActions,
+ ItemContent,
+ ItemDescription,
+ ItemMedia,
+ ItemTitle,
+} from "@/components/ui/item";
+import {
+ type ApprovalMember,
+ approvalNamesNobody,
type SharedUseApproval,
} from "@/lib/plugins/shared-use";
+import { MISSING_TEAM } from "@/lib/teams/names";
+import { teamListQueryOptions } from "@/lib/teams/queries";
export function sharedSectionSentence(
effect: "read" | "write",
@@ -13,10 +29,18 @@ export function sharedSectionSentence(
: "Anyone who can use this Bot can read what this account can read.";
}
+const AUDIENCES: { audience: SharedUseApproval["audience"]; label: string }[] =
+ [
+ { audience: "owner", label: "Only its owner" },
+ { audience: "people", label: "Named teams and people" },
+ { audience: "team", label: "Everyone" },
+ ];
+
/**
* Who may use a shared account through one Bot: the audience the Bot has now, offered as the
- * default, and only ever NARROWED here. Named people are offered only when the Bot is published to
- * named people, because that list is what a `people` approval records.
+ * default, which an admin can change here. Only its owner, everyone in the organization, or the
+ * teams the admin names. Whoever the audience already names (people, and directory groups from
+ * before there were teams) is kept and shown under the named choice.
*/
export function SharedApprovalFields({
value,
@@ -25,41 +49,33 @@ export function SharedApprovalFields({
value: SharedUseApproval;
onChange: (next: SharedUseApproval) => void;
}) {
- const named = value.audience === "people" || value.members.length > 0;
- const options: { audience: SharedUseApproval["audience"]; label: string }[] =
- [
- { audience: "owner", label: "Only its owner" },
- ...(named
- ? [
- {
- audience: "people" as const,
- label: `Named: ${describeApproval({ ...value, audience: "people", outsideInput: false })}`,
- },
- ]
- : []),
- { audience: "team", label: "Everyone" },
- ];
return (
-