Socialize | Topolo Docs

What It Is

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

Its integrations surface now 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 reports whether each provider is production-ready, sandbox-only, setup-required, or still only planned.

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 billing flows now route provider calls through Topolo Nexus while Socialize keeps ownership of prompt construction, domain validation, and persistence.

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.

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 whether each brand can schedule to X, LinkedIn, and Facebook

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.

Auth and Permissions

Socialize uses Auth-managed service IDs, API key scopes, and centralized brand resource binding catalogs. The API worker validates staff bearer tokens through centralized Auth validation and does not keep a local JWT-secret trust path. 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 Nexus-backed flows forward the caller’s bearer token so usage stays attributed to the correct org and user context. Background and service-triggered flows use trusted service-context headers with the brand’s org attribution.

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.

Deployments

Socialize deploys with an application frontend plus worker/API surface documented in the generated system handbook.

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.

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, email, or billing 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, email, or billing flows stop working, verify the worker is calling Nexus rather than a vendor API directly and that Nexus has the required provider keys configured.

Change Log / Verification

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