Skip to content

API: delete an organization, and hold keys, events, the Recorder, push and the realtime socket to one organization - #1897

Open
davidmckayv wants to merge 3 commits into
mainfrom
feat/one-org-spec
Open

davidmckayv wants to merge 3 commits into
mainfrom
feat/one-org-spec

Conversation

@davidmckayv

@davidmckayv davidmckayv commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

The API additions for one person working in several organizations, with nothing shared between them. Spec only: sources, bundle and every generated client, plus the changelog. All of it is additive under /api/v2.

What changes

  • Delete an organization. deleteOrganization, DELETE /api/v2/organizations/{organizationId}/profile, beside updateOrganization. 204 when deleted. Owner only (403 OwnerOnly). A person's own organization and default are refused with 409 OrganizationStays (CONFLICT). 503 OrganizationNotDeleted when it couldn't be finished.

  • An API key acts in the organization it was made in. ApiKey.organizationId (optional, nullable: null for a key made before keys were bound, which acts in default). createApiKey and the apiKey scheme say a key is refused in any other organization. Every install in the field has only default, so no existing key behaves differently.

  • Conversation events name their organization. ConversationActivity.organizationId (optional) in api/asyncapi.yaml. A client ignores a message for another organization.

  • A Recorder connection names its organization. RecorderConnectionGrant.organizationId (optional): the organization the connect code was made in.

  • Push devices are registered per organization. registerDevice, listDevices and deleteDevice were already under the organization's address; their descriptions now say a device gets push notifications only from the person's Bots in that organization.

  • The realtime socket at an organization address. /api/v2/organizations/{organizationId}/realtime/websocket relays the same socket as /api/intelligence/client/websocket, for a member of that organization: new channels organizationThreadStream and organizationTrajectoryCapture and their operations. realtime is clear of api/intelligence-reserved.yaml, which now also reserves the /api/v2/platform root.

  • Deprecated: the role property of updatePerson, in favour of updateOrganizationMember. x-deprecation-date 2026-11-19, x-sunset 2028-05-19, listed in the changelog's Deprecated list. The sunset leaves room for the release that first serves it, since the support window counts 365 days from that release.

  • The support window's tests hold a real deprecation. This is the spec's first deprecation. tests/support-window.test.ts assumed the spec deprecates nothing. Its run of the check also looked up each release's spec by tag, which fetches from GitHub once anything is deprecated, so it timed out in CI. SUPPORT_WINDOW_RELEASE_SPECS now lets the check read release specs from a directory, the test points it at its fixtures, and the tests find the real role deprecation. CI's API spec job still reads the real release specs by tag.

Checked locally

  • bun run api:generate: sources, bundle and clients committed together.
  • bun run api:lint: valid.
  • oasdiff 1.38.0, --fail-on WARN, 365-day deprecation window: no breaking change against main, v1.1.1 or v1.1.0 (no older release has a spec).
  • scripts/support-window.ts check: the window holds, 1 deprecation.
  • api:live:diff against main's asyncapi.yaml: no change breaks a client.
  • bun test api/ shared/tests/api-deprecations.test.ts app/tests/tolerant-reader.test.ts tests/no-intelligence-in-user-copy.test.ts: 99 pass.
  • bun run typecheck, bun run format:check: clean.

…an be held to one organization

Adds deleteOrganization (DELETE .../profile), refusing a person's own organization and default; organizationOnly on a new API key and organizationId on a key; organizationId on conversation events and on a Recorder connection; the realtime socket relayed at /api/v2/organizations/{organizationId}/realtime/websocket; and says a push device is registered per organization. Deprecates the role property of updatePerson in favour of updateOrganizationMember, sunset 2028-05-19, and reserves Intelligence's /api/v2/platform root.
Drops organizationOnly from a new key: every key is bound to the organization it was made in, and a key with no binding acts in default. ApiKey.organizationId says which, and createApiKey, the apiKey scheme and the changelog say so.
…ng the network in tests

The support-window tests assumed the spec deprecates nothing, and their run of the check looked every release's spec up by tag, fetching each from GitHub once the spec marks something deprecated: it timed out in CI. SUPPORT_WINDOW_RELEASE_SPECS reads release specs from a directory instead, which the test points at its fixtures, and the tests now find the real deprecation of updatePerson's role.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant