Organization upgrade and installation

The current source supports owner/admin/member authority, membership scope tags/public data and voluntary departure, plus caller-specific SSO org discovery. This guide describes installation order; local checks do not establish a live deployment or an immutable SDK release.

OAuth ownership storage prerequisite

The ownership/directory split requires oauth_clients.org to contain a valid UUID independently of tenant. Before installing readers or writers that use the split, verify the existing database has that field and correctly populated rows: legacy personal registrations use nil org and nil tenant; legacy tenant registrations use org = tenant. Preserve any already assigned non-nil org on consumer registrations whose tenant is nil. Nil is 00000000-0000-0000-0000-000000000000, not SQL NULL.

The current OAuth repository projects and filters stored org; it does not install this column or backfill old rows. Legacy request compatibility infers omitted org from tenant for inserts/searches, and is not a storage migration. Verify the deployment's reviewed schema/backfill before rollout; no automatic ownership migration is established by this guide. Ordinary updates cannot move registrations between these scopes. Multiple independent tenants per org remain future work. See normalization and isolation.

Install in dependency order

  1. Install compatible shared PHP library/platform source. Keep the existing Management group repositories and configured membership metadata support: organization_manage_group_meta, keyed by the Management membership UUID. The org management controller's ensureStorage() ensures its group, membership, link, metadata and principal repositories.
  2. Install API User's OrganizationManagementTags adapter. Its constructor lazily calls ensureTables() for organization_manage_tag_names and organization_manage_tag_junction; ensureTables() is also available for controlled explicit installation through the application's configured SQL service. Use the shared repository installers, database UUID helpers uuid_bin() / uuid_str(), normal SQL quote setup, and appropriate schema creation privileges. Verify the tables before SSO reads them. SSO does not install them. Preserve existing data; do not replace an existing schema or run test fixtures on production.
  3. Install SSO's /userinfo/orgs endpoint, explicit consented orgs scope and discovery metadata. Verify both public metadata URLs and the configured mTLS gate. The richer projection reads live membership tags and pub. Owner-controlled discovery also requires compatible platform DiscoveryPolicy and OrganizationConfig service methods before the new SSO code is installed.
  4. Install updated Token/PHP source with the Organizations and Emails classes and facade wiring. Existing Token/PHP 0.1.3 ZIPs lack those classes; follow current-source SDK installation.
  5. Install the platform remote organization service and shared bootstrap with M7_LIB_ROOT, M7_PLATFORM_ROOT, and M7_IDENTITY_TOKEN_ROOT pointing at compatible deployment roots. The platform bootstrap needs the SDK root containing packages/token-php/autoload.php, not the CLI package-root form. Optional local imports use the application-local remote_organizations repository and its ensureTables(); live lookup needs no import table.
  6. Install API BigFS and BigFS pickup/client configuration. Register orgs for the BigFS OAuth client and obtain fresh consent; an existing token does not gain it from registration alone. See BigFS organization acquisition.
  7. Install API User and User M7 together for the later role enforcement, read-only modal and departure slices. Those slices add no tables/columns or extra schema migration. The operational viewer → member migration is separate from the shared generic group enum.
  8. Install compatible platform, API User, SSO and User M7 source for the Access → Members / Policy discovery controls. Policy is stored in the existing organization_config; this slice adds no schema migration or new OAuth scopes. Both discovery switches default off for existing and new orgs. An owner must enable the appropriate switch or add an allow rule for BigFS or another consuming app to see the org. Rule order is authoritative.

Acceptance boundaries

Use current-source role, owner app/key, tenant-security, org tags/pub/leave, owner-only discovery policy, SSO projection/discovery, SDK validation, platform and API BigFS checks. Storage and locking suites require a disposable authorized scratch database; browser fixtures use synthetic responses. Release extraction verifies packaging only. Before claiming live rollout, exercise a consented consumer token, sender bindings, signed/encrypted policy if configured, fresh membership changes and departure through the actual deployment.

The platform offline-access accessible-app helper is a remaining role-boundary inconsistency: issued client-credentials search/view/revoke and device app-grant inventory use active Management membership in stored org, without filtering the stored owner role. They exclude creator-only access but are broader than owner-only registration/key management. The current owner-boundary fixtures cover registration/key routes; they do not establish owner-only issued-grant access. See issued-record behavior.

Admin delegation and admin app/key inventory remain deferred. The standalone catalogue UI and shared tag pool were cancelled; membership expiry was not added. BigFS transports/displays facts, while bucket authorization and each other product's scope semantics remain separate work. Blog adoption is future work. No schema replacement, production fixture run or release creation is part of this upgrade guide.