Topolo Developers

Public overview of the authenticated Topolo developer portal and its submission/request workflows.

publicverified 2026-07-31developersportalauth

What It Is

Topolo Developers is the authenticated developer console for teams shipping into the Topolo ecosystem, and it also hosts the staff-only internal review and commerce operations areas for app submissions, Android and iOS mobile app artifacts, build requests, developer workspaces, app pricing, marketplace status, and payout readiness.

Architecture

The application is a standalone Cloudflare Worker at developers.topolo.app with Worker static assets, same-origin API handlers, bounded D1 directory/workflow indexes, and SQLite Durable Object partitions keyed by application. It owns mobile artifact catalog metadata for Android and iOS, complete published app manifests, and per-app machine-action definitions for SDK, CLI, and MCP agents. Topolo Auth supplies login, session refresh, API-key records and catalogs, app-switcher entitlement state, approved-app registration, and bounded per-app permission projections used by Developers during action discovery. The Credentials route uses the shared multi-application API-key screen rather than a Developers-owned credential manager.

Public developer-program discovery still begins on TopoloOne, but the primary public handoff now lands on developers.topolo.app/signup. Signup creates the developer workspace account first, then onboarding continues inside the signed console instead of through a public marketing form.

Workspace Management

The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces.

Runtime Surfaces

The primary runtime host is https://developers.topolo.app, with https://developers.topolo.app/signup serving as the public signup entrypoint from the marketing site. Signed publisher routes include /onboarding, /overview, /apps, /credentials, /requests, and /settings. Internal staff review routes live at /review/app-submissions and /review/build-requests; internal Topolo commerce operations routes live under /admin/*.

API Reference

Topolo Developers owns the signed /api/developer-console/* backend contract for workspace summary, onboarding, app records, app action definitions and publication, mobile artifacts, submissions, build requests, transfer claims, internal review workflows, and internal commerce controls. It also owns cursor-paged public /api/apps catalog responses for installable Android artifacts by default, with iOS metadata available through the platform query. Responses contain artifacts and a page continuation object; limits are capped at 100. It consumes centralized Auth API-key, app-switcher entitlement, service-registration, and per-app permission routes documented in /reference/api/topolo-auth. Published action definitions can also carry a clean-room agent contract: public docs, canonical resource identifiers, effects, actionable errors and recovery, verification steps, rollback and next actions, and examples. Developers validates declared agent contracts and their root input/output schemas before publication, preserves them in the application partition, includes them in credential-scoped catalog responses, invalidates catalog digests when that metadata changes, and rejects a sync when the committed partition digest does not match the exact action set that was sent. Atomic manifest imports return the durable partition action count and sha256-v1 digest after commit. The canonical publisher independently computes the expected digest and stops publication when that committed count, algorithm, or digest is missing or stale. Public application discovery is cursor-based: /api/store/catalog returns at most 100 applications plus page.hasMore and page.nextCursor, /api/store/search returns at most 40 ranked matches, and exact app reads hydrate one application partition. This keeps request cost bounded as the number of applications grows. Public /api/apps catalog responses include approved app artifacts whose Developers marketplace status is active or production_ready; developer-only, draft, paused, and archived apps stay out of the public artifact catalog. This lets production-ready Topolo-owned mobile APKs support device installs without promoting those mobile records into the public TopoloOne app-store catalog. The signed app-detail App Store marketing editor uses the same Developers-owned store taxonomy that TopoloOne and topolo.io/app-store consume, so publishers edit the same broad store section and detailed store category fields that appear on public catalog cards. Its public badge selector controls the visible App Store badge/tone, not runtime app access, and the public stage wording is derived from that badge instead of edited separately. Signed app forms label public store distribution as Topolo App Store. The underlying API value remains distributionModel = "marketplace" for compatibility, but the user-facing flow is not limited to third-party apps.

Publication policy follows ownership. Approved operators use restricted topolo-platform apps scaffold --provision and topolo-platform apps reconcile --apply for Topolo-owned manifests. Customer developers use the public, confirmable apps.scaffold and apps.reconcile action contracts exposed through CLI/MCP discovery. Third-party changes remain subject to organization approval and default to organization-internal distribution; requesting Topolo App Store distribution cannot self-approve the listing. Operator-only Developers admin.* contracts are excluded from public agent discovery.

Auth and Permissions

Topolo Developers uses the shared Topolo browser auth client and Auth-managed route family. It should not introduce a separate account system. The app uses provisioned app-id bindings at runtime: APP_ID=app_NjDq9G9qyyjr for its own browser/backend Auth context, AUTH_APP_ID=app_mKShvFV4c8Z3 for the legacy consent-forwarding loading surface, P2P_APP_ID=app_4BzeLqH0wCve for internal P2P sync calls, and TOPOLO_SEED_APP_ID=app_topolo_seed for staging seed routes. Plain sign-in is workspace-first: the signed console expects a Developers-owned developer profile for the current Auth organization rather than creating arbitrary workspaces on first access. Internal commerce operators can set approved app visibility to active, developer_only, draft, paused, or archived. Platform-wide commerce access is reserved for Auth users whose role is super_admin in the admin organization, while delegated staff access still comes from explicit Developers commerce:* permissions. developer_only keeps the app usable only by the developer owner organization, with Topolo Auth enforcing that status across launcher, SSO, validation, API-key, and service-context checks.

Data Ownership

Topolo Developers owns authenticated console UX, workspace-scoped developer profiles and records, app drafts, complete published app manifests, app action definitions and the credential-scoped action catalog consumed by SDK, CLI, and MCP, mobile artifact metadata, submissions, build requests, transfer state, internal review-state data, app marketplace/pricing controls, payout-account readiness, and payout ledger events. Topolo Auth owns identity, sessions, app-scoped workspace identity and lifecycle, centralized API-key catalogs, app-switcher installation entitlements, approved-app registration into the shared service catalog, and bounded per-app entitlement and permission projections. The Topolo Technology workspace also carries first-party Topolo mobile artifact records. Topolo Feed, Topolo Provision, and Topolo MDM Mobile have system-specific records. Developers may retain Android/iOS identifiers and artifact history for the 22 archived TopoloMobile* Flutter repositories, but those catalog rows are not proof of an active source or release pipeline. Current mobile behavior comes from each active application's topolo.mobile-experience.json, TopoloProvision, or TopoloMDM; only artifacts built from an active owning repository may be promoted.

Mobile Experience

The checked-in mobile experience contract is approved in web mode. Its fallback route is /overview, its offline policy is undefined, and it requires organization context.

Published permissions: none.

  • No native routes are published yet.

The native clients consume this manifest as an explicit rendering contract. A web mode record intentionally opens the product web experience; native_capability publishes the listed native routes and actions. Do not infer unlisted native behavior.

Deployments

Topolo Developers deploys as the topolo-developers-production Worker on developers.topolo.app and the topolo-developers-staging Worker on developers.stg.topolo.us. The catalog cron worker points embeddings sync at the matching environment's /api/catalog/embeddings endpoint. The Worker assets binding serves the first-party browser icon assets from /favicon.svg and /favicon.ico so the deployed app tab uses the canonical Developers icon. The same Worker serves the mobile app catalog routes that device installers and sales-demo surfaces consume. Android APK artifacts for first-party mobile catalog rows are stored in the shared topolo-apks R2 bucket and served from the canonical https://apk.topolo.app host through immutable checksum-suffixed URLs plus latest aliases.

Developers is also the canonical presentation owner for first-party catalog names and icons. Its guarded publication path requires approved first-party control records to have an icon, verifies that the published registry projection carries the same icon, and exposes that projection to Auth and shared clients without a generic identity fallback. Applications classified as organization_internal remain valid control-plane records but are deliberately excluded from the public registry projection.

Failure Modes

  • developers.topolo.app serves the wrong Worker deployment or stale assets
  • callback and deep-link routes fail because the SPA fallback is missing
  • the portal drifts back into TopoloOne ownership instead of remaining a separate application
  • the local Developers API contract or the shared Auth identity/service-registration contract drifts from the portal UI assumptions
  • mobile artifact metadata is edited outside Developers and the public /api/apps catalog no longer matches approved application records
  • internal app commerce controls drift from Auth service-catalog marketplace metadata after approval
  • app visibility drifts so a developer-only app remains visible through public catalog, launcher, API-key, or service-context access
  • app action definitions drift from the service manifest permission catalog and fail Auth publish validation

Debugging

Start with /systems/topolo-developers, then verify the served Worker deployment and Auth session state before changing portal UI code.

Use It

Open Topolo Developers for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-developers --json
topolo actions --service topolo-developers --json
topolo actions capabilities --service topolo-developers --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

  1. Confirm the active identity and organization with topolo whoami --json.
  2. Discover Topolo Developers and select one published action rather than guessing a route.
  3. Inspect its input/output schemas and published example.
  4. Validate and plan the exact payload; obtain confirmation for a mutation.
  5. Execute and perform every published verification step.

Change Log / Verification

  • Clarified first-party automatic projection and third-party marketplace approval boundaries on 2026-08-10.

  • Reconciled action-catalog enrichment, runtime authorization, and versioned import normalization through apps/TopoloDevelopers origin/staging 4ee465b77d8c on 2026-07-29. Runtime-authorized actions remain discoverable, while their owning application makes the final organization, resource, and input decision at call time.

  • Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found.

  • Verified the web mobile experience contract and its 0 published route(s) against apps/TopoloDevelopers origin/staging 98d9b563c53e on 2026-07-27.

  • Reconciled this page against apps/TopoloDevelopers origin/staging 753ff39fe7f5 on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract.

  • Added validated clean-room action metadata on 2026-07-14 so third-party CLI and MCP agents can discover schemas, examples, effects, recovery, verification, rollback, and next actions without repository access.

  • Replaced the Developers credential manager on 2026-07-12 with the shared multi-application API-key screen while preserving workspace access gating and Auth-backed application discovery.

  • Replaced global full-manifest catalog reads on 2026-07-11 with a compact paginated directory, bounded search, and per-application manifest hydration.

  • Added per-application SQLite partitions for complete published app manifests on 2026-07-10 so application count does not grow a global full-manifest storage object.

  • Reconciled workspace verification on 2026-06-28 against apps/TopoloDevelopers commits through fef0d94; reviewed 261 commits since 2026-06-04, including fef0d94 feat(catalog): bulk seed sync (publish all 47, then 2 bulk S2S calls); b18b735 feat(catalog): seed registry from Auth's full service catalog (47, not 11); a733358 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 8bfcd02 feat(catalog): seed backfills Auth org-service app_id mapping via S2S.

  • Added Developers-owned app action definitions on 2026-06-04 so publishers can manage machine-callable SDK, CLI, and MCP operations while Auth remains the permission-scoped projection boundary.

  • Replaced runtime Developers Auth slug lookups on 2026-05-13 with deployment app-id bindings so browser auth, shared shell, widgets, store proxy calls, Auth registration calls, P2P sync calls, and seed routes do not call Auth to discover stable app ids.

  • Verified Developers staging portal build and catalog-cron staging metadata on 2026-04-30.

  • Corrected the app-detail App Store marketing editor on 2026-04-27 so public catalog category and subcategory controls stay aligned with the Developers-owned store read model and the badge selector is no longer labeled as runtime status.

  • Simplified the app-detail App Store marketing editor on 2026-04-27 so existing TopoloOne store categories hydrate from developer_apps.marketplace_subcategory, the broad taxonomy bucket is labeled as a store section, and duplicate manual stage-label editing is removed.

  • Renamed the signed app-form distribution label on 2026-04-27 to Topolo App Store while preserving the existing API value.

  • Restricted the Developers platform-admin bypass to Auth super_admin users in the admin organization on 2026-04-23 while preserving explicit commerce:* staff permissions.

  • Switched the canonical first-party APK host from topoloapk.topolo.app to apk.topolo.app and promoted the TopoloProvision Android APK catalog row to core 1.2.172 on 2026-04-23.

  • Added developer-only app visibility controls backed by Auth service-status enforcement on 2026-04-23.

  • Published all 22 retained Topolo Mobile Flutter Android APKs from Developers to the shared topolo-apks R2 bucket and promoted their catalog rows to installable artifacts on 2026-04-23.

  • Finalized all 22 retained Topolo Mobile Flutter app package identifiers and removed 8 superseded mobile app records from the Developers catalog backfill on 2026-04-23.

  • Marked ClockMe, Inspirational, and Hiero as the first package-identifier-finalized retained Flutter batch on 2026-04-23.

  • Added Topolo Technology's retained Flutter mobile apps to Developers on 2026-04-23 as Topolo Mobile app records with Android and iOS metadata.

  • Added Topolo Technology's first-party mobile app records to Developers on 2026-04-23.

  • Moved mobile app artifact catalog ownership into Developers on 2026-04-22 so Android and iOS release metadata is managed from the app detail workflow and exposed from Developers-owned /api/apps routes.

  • Corrected the public Developers sign-in CTA on 2026-04-21 so first-party users open the app-origin shared login screen instead of hosted Auth.

  • Corrected the signed Credentials service selector on 2026-04-21 so Auth-backed API-key metadata requests use canonical app ids instead of organization-service access-row ids.

  • Backfilled the Topolo Technology publisher workspace and first-party Topolo Platform app records in production Developers D1 on 2026-04-21 so Topolo can use the developer console like an external publisher.

  • Seeded the shared Topolo demo suite developer workspace in production on 2026-04-20 so platform-wide auth audits can verify the signed console with demo@topolo.io.

  • Cut the signed Developers data path over to its own Worker + D1 backend on 2026-04-15 and removed request-time schema bootstrap in favor of checked-in D1 migrations plus a repo-level CI gate

  • Added internal Topolo commerce operations routes on 2026-04-16 so super admins can manage developer workspace state, app pricing/marketplace state, payout readiness, and payout ledger events inside Topolo Developers

  • Re-homed internal app-submission and build-request review into Topolo Developers on 2026-04-13 so staff operators now review queues from the same application boundary as publisher intake

  • Rebuilt Topolo Developers as the account-first developer console on 2026-04-13 so signed users now continue through onboarding, private app setup, public listing submission, and Auth-backed credentials inside the standalone app

  • Added the public signup handoff at developers.topolo.app/signup on 2026-04-10 so the marketing site can route developers into one clear entrypoint

  • Split the authenticated developer portal into the standalone Topolo Developers application on 2026-04-10