01 · Register the app
Create the app_id in Registered Apps. Every request to this service carries that app_id; unknown ids are rejected with 404 unknown_app_id.
POST /api/social/status?app_id=appetite-example
02 · Configure the brand
Set brand name, domain, logo, accent colour, handles, enabled platforms, share template defaults, webhook URL and deep-link scheme.
enabled_platforms: ["instagram","tiktok"]
template_settings: { template: "editorial", defaultOrientation: "9:16" }03 · Call the central API
Never implement Instagram or TikTok inside the product app. Ask this service to start a connection, publish, or build a share card.
POST /api/social/connect
{ "appId": "appetite-example", "provider": "instagram",
"userId": "u_123", "returnUrl": "https://example.com/settings/social" }04 · Render the universal share sheet
Post a normalized SocialShare object. The service mints a share/referral id, stores asset metadata and returns the attributed canonical URL for native sharing.
POST /api/social/share-card
{ "appId": "appetite-example", "objectType": "recipe", "objectId": "r_44",
"title": "…", "canonicalUrl": "https://example.com/r/44",
"template": "editorial", "orientation": "9:16", "hashtags": ["bbq"] }05 · Receive the callback
The provider returns to this service, not to the product app. The signed state is verified, then the browser is routed back to the original returnUrl with a result flag.
GET /api/social/callback/instagram?code=…&state=<hmac-signed> → 302 https://example.com/settings/social?social_connect=…&provider=instagram
06 · Track attribution
Every share carries ref=<share_id> plus UTM parameters mapped back to app, user and content object, so acquisition can be attributed end to end.
https://example.com/r/44?ref=Kd8x1PqA&utm_source=appetite-social-os&utm_medium=share&utm_campaign=recipe:r_44
Endpoint reference
| POST | /api/social/connect | Start a provider connection; returns signed OAuth state |
| GET | /api/social/callback/:provider | Verify state, route the browser back to the origin app |
| POST | /api/social/publish | Queue a publication (draft / scheduled) |
| POST | /api/social/share-card | Create share asset metadata + attributed link |
| GET | /api/social/status | Service and provider activation status |
| GET | /api/social/accounts | Connected accounts for an app |
| GET | /api/social/analytics | Publication and share attribution rollups |
Security boundaries
- • Provider secrets are read inside server handlers only and never returned to any client.
- • All social tables are server-only; no browser role can read connections, tokens or credentials.
- • OAuth state is HMAC-signed with a nonce and a 10-minute expiry, then verified before any redirect.
- • Nothing is faked: with credentials missing, connect returns 503 provider_not_activated and publish stores a labelled draft.