Socialize

Public overview of the social publishing platform, brand-scoped resource bindings, and content operations.

publicverified 2026-08-01socialpublishingbrands

What It Is

Socialize is the social publishing and campaign platform for posts, media, analytics, integrations, and brand-scoped publishing workflows.

Its integrations surface returns Facebook Pages and eligible Facebook Groups together, preserves the exact Facebook target, LinkedIn organization, or Instagram account chosen for a post during later edits, and combines live Nexus account state with Socialize-owned brand target selections and publishing health.

Architecture

Socialize combines the application surface with a worker/API runtime that exposes brand-scoped content operations and analytics.

Its AI-assisted text generation, image generation, trend workflows, invitation email delivery, and connected-provider credential handling route through Topolo Nexus while Socialize keeps ownership of prompt construction, domain validation, publishing intent, and content persistence. Nexus owns connected-account identity, avatar/profile data, lifecycle, scopes, expiry, and encrypted tokens; Socialize stores only the stable Nexus reference plus brand-specific target selections and runtime health. Billing and referrals are platform-level surfaces outside the Socialize workspace and API. Socialize requires Topolo Brand in every deployed environment and resolves a published Brand version for the active Socialize brand before text or programmatic-media generation. Readiness and generation fail closed when the Brand binding, service identity, or canonical snapshot is unavailable; there is no unbranded compatibility path. The generator uses only approved channel-compatible claims and CTAs, embeds the canonical primary logo, derives readable artwork colours from the published palette, and records the exact kit and version used. Manual brand colour, font, and name overrides are no longer accepted by these generation routes. The browser workspace keeps the Improve Topolo contribution entrypoint inside the shared account menu rather than rendering a floating report button over product workflows.

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

See /systems/socialize for the current runtime host and deployment surfaces.

API Reference

Use /reference/apps/socialize and the generated OpenAPI detail for routes, operations, and request examples.

Topolo CLI and MCP clients can discover and run Socialize actions for brands available to their credential. The action catalog includes typed post creation, campaign creation and scheduling, publishing-readiness checks, and follow-up reads for verification. Roles and brand-bound API keys remain constrained by the same platform and Socialize permissions as the browser.

Trend And Queue APIs

Socialize now exposes a trend-native handoff for connected automation and mobile review flows:

  • /api/trends returns normalized trend or shared-seed items for a brand
  • /api/content-strategy/suggestions/generate-from-trends creates platform-specific draft suggestions directly from those items
  • /api/seeds/share stores time-sensitive shared seeds and routes them to one, selected, or all brands
  • /api/content-ops/deck returns a freshness-ranked approval deck for mobile review
  • /api/brands/:brandId/publishing-readiness reports token-aware scheduling readiness for X, LinkedIn, Facebook, Instagram, Threads, TikTok, and YouTube

Trend-backed suggestions include source attribution, freshness, and dedupe metadata so downstream schedulers can act on them safely. The mobile app also accepts native share-sheet intake. A link or post shared into Socialize from another app is converted into a reusable seed, then routed from a single brand list with a quick-select-all action before suggestion generation starts. Socialize infers one, selected, or all targeting from that choice. The iPhone app also falls back to the shared App Group payload store on launch and resume so cold-start shares still land in the brand-targeting flow. The same mobile approval deck now supports Tinder mode for swipe review with a shared media-and-copy scroll flow, Story mode for an Instagram-story-style review surface with full-width left or right tap navigation, a dedicated media panel, one shared vertical scroll flow for media and copy, and the same edit sheet opened by double-tap or press-and-hold, and Feed mode for a scrollable queue with per-item actions, context controls, inline media controls, and expandable long-copy handling. Socialize stores that preference on-device so the app reopens in the operator's chosen review layout. Scheduled posts can be reverted to drafts from the browser posts list; the API clears the schedule and returns the updated draft state before the UI reports success. Campaign scheduling creates durable posts for each configured day/time and enabled platform, and retries do not duplicate those occurrences. Scheduled publishing uses the active connection for the target brand and platform. It prefers the post author's connection when available, then falls back to another active brand connection so approved brand content can publish even when the scheduler actor is not the user who connected the social account. X connections request read, write, media upload, and offline refresh scopes, and profile hydration uses the current X API host before the legacy api.twitter.com API host. Before publishing, the scheduler reloads the post row so current copy and rescheduled times win over older queued snapshots. Expired X tokens are refreshed through the API worker's Auth-verified internal service route, keeping provider OAuth client secrets on the API surface while scheduled publishing receives the fresh connection token.

Auth and Permissions

Socialize uses Auth-managed service slugs, API key scopes, and centralized brand resource binding catalogs. The browser, mobile app, and API worker resolve the topolo-socialize slug through Auth at runtime instead of shipping a concrete app ID in source or static assets. The API worker validates staff bearer tokens through centralized Auth validation and does not keep a local JWT-secret trust path. Browser brand selection and API-key brand binding checks now share the platform resource-context helper while Socialize continues to own brand records and brand membership roles. Its browser session flow now uses the shared Topolo cookie-refresh auth client rather than a Socialize-specific browser auth implementation. The Socialize CLI now uses the same shared Topolo auth client for direct credential login and token validation instead of its own Auth protocol implementation. Socialize also defaults any missing Auth role claim to member across its CLI and worker-side token intake paths. The browser sign-in callback requires Auth's one-time sso_code handoff on /auth/callback and delegates callback-code redemption to the shared Topolo Auth client before storing a local session; direct token callback URLs are not accepted. The embedded browser login keeps form controls interactive while background session bootstrap runs, and the browser app restores the short-lived access token from same-tab session storage after a normal refresh before falling back to cookie refresh. Auth platform_super_admin and platform_admin users operating from the admin tenant can administer brand invite, member-management, and integration-disconnect mutations even when they are not stored as local members of that brand, while org-scoped super_admin users still follow the normal brand membership manage checks and owner-only operations remain restricted. The mobile app now holds on the Socialize splash screen while a saved session is being restored instead of briefly flashing the login form first. main() preloads the mirrored local session snapshot before the router renders, and the app root stays on splash until auth bootstrap completes without bailing out on a fixed startup timeout. It waits briefly for iPhone protected data before reading secure storage, restores from locally persisted auth state before the background user refresh completes, and if secure storage comes back empty or throws it falls back to a mirrored local session snapshot before reconstructing a local user from access-token claims, so reopening the app does not depend on an immediate network round-trip to keep the user signed in. The login form now exposes iPhone autofill-friendly email and password fields, remembers the last successful email locally, and commits the autofill context on successful sign-in so iOS Passwords can help reuse credentials. If biometric unlock is enabled, Socialize now gates the restored session behind Face ID or Touch ID when the app returns from the background.

User-driven AI and email Nexus-backed flows forward the caller's bearer token so usage stays attributed to the correct org and user context. Social-provider OAuth, token-refresh, callbacks, publishing, and account-management flows use Auth-minted service context with the brand's org attribution, delegated user ID where applicable, and the registered app_topolo_socialize Nexus app ID. Nexus is the sole source of connected-provider credentials and lifecycle state. Browser inventory is a hydrated view of that live Nexus state plus Socialize-owned brand selections and runtime metrics; local rows contain no provider token or provider profile copy.

Data Ownership

Socialize owns the actual brand and publishing resources while Auth owns the bindable-resource index consumed by TopoloOne. Brand owners can move an existing Socialize brand to another accessible Topolo Auth organization. The brand keeps its Socialize ID and content history while its org-scoped ownership moves to the target organization. The transfer flow uses a searchable target-organization picker and copyable target organization ID confirmation before the ownership move is submitted.

Mobile Experience

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

Published permissions: posts:read, posts:write, calendar:read, calendar:write, accounts:read, accounts:write.

  • /posts uses /api/posts with the record.list template and socialize.posts.list data source.
  • /posts/:id uses /api/posts/:id with the record.detail template and socialize.posts.detail data source.
  • /campaigns uses /api/campaigns with the record.list template and socialize.campaigns.list data source.
  • /campaigns/:id uses /api/campaigns/:id with the record.detail template and socialize.campaigns.detail data source.
  • /brands uses /api/brands with the record.list template and socialize.brands.list data source.
  • /brands/:id uses /api/brands/:id with the record.detail template and socialize.brands.detail data source.

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

Socialize deploys with an application frontend plus worker/API surface documented in the generated system handbook. The Topolo-owned staging mirror runs the frontend at socialize.stg.topolo.us and the API worker at socialize-api.stg.topolo.us. Standardized AI flows no longer rely on app-local Google or xAI provider secrets in the worker runtime. User-driven routes forward bearer auth to Nexus, and background worker flows use the trusted service token plus brand org attribution. Trusted operator automation can generate post media through an internal Socialize image route, but the generated assets still pass through the same Nexus-backed image handlers and Socialize R2 media storage as browser-generated images.

Failure Modes

  • missing brands.read scope for resource binding workflows
  • wrong API origin or CORS misconfiguration
  • Auth catalog drift for brand-scoped keys
  • Nexus connectivity or auth-context forwarding is missing for AI or email routes
  • worker code regresses to a direct vendor fallback instead of using Nexus

Debugging

Use /systems/socialize for runtime, bindings, and deployment detail, and /reference/apps/socialize for API operations and OpenAPI-backed routes.

If AI or email flows stop working, verify the worker is calling Nexus rather than a vendor API directly and that Nexus has the required provider keys configured.

Use It

Open Socialize 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 socialize --json
topolo actions --service socialize --json
topolo actions capabilities --service socialize --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 Socialize 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

  • Completed and staging-verified the Nexus-only connected-provider boundary on 2026-08-01 at Socialize source 0c7fecd2fd61131e5ceb305b76bccaae3271fa99; the API and scheduler hydrate Nexus state, local storage is reference/selection/runtime-only, and provider callbacks and refreshes update Nexus first.

  • Verified the native_capability mobile experience contract and its 6 published route(s) against apps/TopoloSocialize origin/staging b63b0f5f25bf on 2026-07-27.

  • Adopted immutable Topolo Brand versions for generated copy and programmatic media on 2026-07-15, including approved claim and CTA enforcement, canonical logo embedding, readable colour selection, and claim-safe deterministic fallbacks.

  • Verified agent-operated post and campaign workflows on 2026-07-14, including canonical brand isolation, server-derived actors, seven-provider publishing readiness, typed action contracts, durable campaign cadence expansion, and follow-up verification actions.

  • Reconciled workspace verification on 2026-06-28 against apps/TopoloSocialize commits through 0028d6e; reviewed 116 commits since 2026-06-18, including 0028d6e chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); 5c65539 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); ce0206f Defer Socialize bug reporter startup bundle; fdfe1c2 Split Socialize startup shell bundle.

  • Removed hard-coded Socialize Auth app IDs on 2026-05-13 so browser login, launcher, mobile auth bootstrap, API-key management, seed sync, notification events, and worker auth validation use slug-resolved app identity.

  • Adopted the shared resource-context package for brand request context and API-key binding parsing on 2026-06-16.

  • Removed the floating browser Improve Topolo button on 2026-05-12 so Socialize uses the shared account-menu contribution entrypoint while preserving the report modal and keyboard shortcut.

  • Fixed the production integrations route on 2026-05-06 so browser-driven Socialize integration inventory and account-management flows call Nexus with the Socialize worker service client plus delegated user/org attribution while preserving Socialize-owned local connection rows.

  • Removed the dummy Socialize admin page on 2026-05-06 so platform administration is no longer shown as a Socialize workspace surface.

  • Made Socialize integration inventory refresh visible on 2026-05-06 so connected accounts do not appear without an in-page status cue.

  • Reduced Socialize integrations loading latency on 2026-05-06 so browser inventory reads no longer wait on Nexus credential lookup or connection synchronization before rendering connect actions.

  • Verified scheduled publishing connection resolution on 2026-05-02 so approved brand posts can publish through the brand's active platform connection even when the post author differs from the connected account owner.

  • Removed reachable Socialize billing and referral routes on 2026-05-06 so billing, referrals, and subscription rewards remain platform-level surfaces instead of app-local Socialize API or workspace features.

  • Verified Socialize deploys against the shared CloudControl short-lived token wrapper on 2026-05-06; Socialize stays on the existing deploy Wrangler path until the Cloudflare Worker versions endpoint accepts the staging API worker binding set.

  • Updated the X OAuth connection flow on 2026-05-02 so image publishing requests media-upload permission and profile hydration tries the current X API host before the legacy api.twitter.com API host.

  • Verified scheduled queue rehydration on 2026-05-02 so edited scheduled posts publish with the current copy and schedule instead of stale queue-message snapshots.

  • Verified scheduled X token refresh on 2026-05-02 so the scheduler uses the API worker's internal refresh route rather than requiring X OAuth client secrets in the scheduler worker.

  • Verified internal Socialize image generation on 2026-05-02 so trusted operator automation can create post media through the same Nexus-backed image handlers and R2 storage used by browser image tools.

  • Aligned Socialize Nexus service-token calls with the registered app_socialize app ID on 2026-05-02.

  • Verified the isolated Topolo Staging deployment on 2026-04-30; socialize.stg.topolo.us and socialize-api.stg.topolo.us/health returned HTTP 200.

  • Verified the Socialize integration readiness contract on 2026-04-24 so LinkedIn Company now reads from dedicated production secrets, Instagram OAuth requests publish scopes that match Meta's current content-publishing docs, TikTok is explicitly marked sandbox-only while TIKTOK_USE_SANDBOX remains enabled in production, and planned providers are no longer treated as production-ready publish targets in the browser compose flow.

  • Corrected Socialize role normalization on 2026-04-24 so CLI and worker-side token intake resolve missing Auth role claims to member.

  • Verified Socialize publish-target persistence on 2026-04-24 so Facebook Group targets now reach the browser integrations flow, edited posts retain their explicit Facebook, LinkedIn, or Instagram destination, and scheduled Instagram publishing uses the saved account target.

  • Verified platform-admin brand invite and member administration on 2026-04-24 so only platform_super_admin and platform_admin sessions from Auth's admin tenant can revoke invites, disconnect integrations, and manage brand team state without a local member row, while owner-only operations remain restricted.

  • Verified brand transfer confirmation and invite revocation on 2026-04-23 so owners can search target organizations, copy the target organization ID, revoke pending invites reliably, and keep the non-member team-management bypass restricted to admin-tenant platform roles.

  • Verified brand organization ownership transfer on 2026-04-23 so an existing brand can move to another accessible Topolo Auth organization without changing its brand ID or content history.

  • Verified scheduled-post revert-to-draft handling on 2026-04-23 so the API response returns draft state before the browser reports success.

  • Verified browser login controls and same-tab refresh restore behavior on 2026-04-23 so the embedded sign-in form remains usable during background bootstrap and refresh no longer loses the short-lived app session before cookie refresh completes.

  • Delegated Socialize browser callback-code redemption to the shared Topolo Auth client on 2026-04-18 so the web helper no longer owns a direct /sso/exchange fetch.

  • Verified the Socialize browser Auth callback on 2026-04-17 so it accepts only one-time sso_code handoff values and no longer exposes direct-token callback routes

  • Updated the Socialize CLI axios dependency to the patched 1.14.0 line to pick up upstream denial-of-service fixes on 2026-04-02

  • Verified persistent mobile session restore without the transient login flash and without requiring an immediate network user refresh, including preloading mirrored local session state in main(), a root-level splash gate, saved access-token claim restore, and a protected-data wait on iPhone when secure storage is not readable or throws immediately at launch, on 2026-04-02

  • Verified iPhone autofill-aware login fields, last-used email hydration, and biometric quick-unlock gating for restored sessions on 2026-04-02

  • Verified the simplified single-list brand targeting flow for native share-sheet intake on 2026-04-02

  • Verified story-mode left/right navigation across the full mobile screen width plus a single shared media-and-copy scroll flow on 2026-04-02

  • Verified staged mobile media uploads through the authenticated mobile API client on the protected Socialize host, plus shared media-and-copy scrolling in Tinder mode, on 2026-04-02

  • Verified shared bottom-sheet editing for swipe/story review plus the dedicated story media panel and view-mode copy on 2026-04-02

  • Verified persisted Tinder, Story, and Feed review modes for the mobile approval deck, with feed-mode context controls attached to each item plus inline media and Read more handling in feed cards, on 2026-04-02

  • Verified the trend, share-seed, and publishing-readiness handoff surfaces on 2026-04-01

  • Verified native Socialize share-sheet intake into the brand-targeted seed flow on 2026-04-01

  • Verified iPhone cold-start share payload recovery from the shared App Group store on 2026-04-01

  • Standardized Socialize browser auth on the shared Topolo auth client on 2026-03-31

  • Standardized Socialize CLI auth on the shared Topolo auth client on 2026-03-31

  • Verified against the current centralized brand resource-binding model on 2026-03-30

  • Verified the Nexus-backed Socialize text, image, email, and billing call paths on 2026-03-30