Skip to content
MSO CloudDocumentation

Platform API and events

On this page

In short#

The Platform API v1 is how a connected app reads from MSO Cloud, and the event stream is how MSO Cloud tells the app something changed. Reads use short-lived, single-organization access tokens with one scope per data plane; events are HMAC-signed, retried and deduplicated by event id.

Platform API v1: what runs before a handler returns data1 · Verify tokenES256, issuer JWKSaud = platform audiencetyp at+jwt, exp, jti401 invalid_token2 · ScopeOne scope per handlerscope claim is spliton spaces403 insufficient_scope3 · Org matchPath org_id must equalthe token org_id(UUID shape first)403 org_mismatch4 · QueryRuns in that org'sRLS transactionCursor pages, limit <= 200404 not_found5 · ResponseZod-parsed body,no-store, narrow fieldserror body is typed429 rate_limited (events)Reads with platform:orgs.read, :entitlements.read, :social.read; writes with :events.writeAccess tokens live 600 s or less; the JWKS is cached 10 min, refetch cooldown 30 sUnset PLATFORM_ISSUER or PLATFORM_JWKS_URL: every route answers 404
One gate per route: requirePlatformScope with a string-literal scope. The token holds exactly one org_id.

Authentication and scopes#

An app gets an access token from the issuer: a client-credentials token for org-level jobs, or a user-delegated token. The app asks for one organization with a resource indicator, resource=https://msocloud.net/api/platform/orgs/<org_id>. The issuer asks MSO web whether the app is installed, enabled and entitled for that org (and, for a user token, whether the user is a member) and mints nothing otherwise.

Token property Value
Format RFC 9068 JWT, typ at+jwt, signed ES256
Audience https://msocloud.net/api/platform
Organization Exactly one org_id claim; a path organization that differs gets org_mismatch
Lifetime 600 s at most
Required claims exp, iat, jti, sub, client_id, scope, org_id
Scope Plane it opens Used by
platform:orgs.read Org structure: caller, launcher tiles, members, brands me, me/launcher, members, brands
platform:entitlements.read App entitlements of the org entitlements
platform:social.read Third-party market-intelligence plane: social trends social/trend-feed (four routes), social/trends, social/trends/counts
platform:events.write App-to-MSO events POST events

There is one scope per data plane. The marketplace and marketing planes have no scope because no app reads them. A satellite manifest lists the scopes it may request.

Endpoints#

All paths are under /api/platform/v1. Lists use cursor pagination: limit 1 to 200 (default 100) and an opaque cursor; the response carries next_cursor.

Method and path Scope Returns
GET /me orgs.read The user, every org membership (not capped), active org and brand, super_admin
GET /me/launcher orgs.read One tile per app for the active org: app_id, name, launch_url, state enabled, not_enabled or expired
GET /orgs/{id}/members orgs.read user_id, email, name, role, brand_ids, disabled
GET /orgs/{id}/brands orgs.read id, slug, name
GET /orgs/{id}/entitlements entitlements.read Per app: plan, limits, valid_to, status (active, trial, suspended, expired)
GET /orgs/{id}/social/trend-feed social.read The org's feed grant and the dataset state; see Trend feed
GET /orgs/{id}/social/trend-feed/items social.read Every usable row of one slice, with its revision
GET /orgs/{id}/social/trend-feed/history social.read Every retained history row of one window, with its revision
GET /orgs/{id}/social/trend-feed/search social.read The vendor's keyword search, proxied and cached
GET /orgs/{id}/social/trends social.read Deprecated since 0.5.0, removed in 1.0. Hourly ranking snapshots: keyword, platform, observed_on, mentions, engagement; filters brand_id, from, to
GET /orgs/{id}/social/trends/counts social.read Deprecated with the route above. Daily row counts of the same rows, for reconciliation; window of 366 days at most
POST /events events.write 202 {event_id, duplicate} for a content.published event

A metric the feed did not report is null, never 0. The ID token carries at most 50 organizations; past that orgs_truncated is true and the app calls GET /me.

Errors are {error, error_description?} with invalid_token (401), insufficient_scope, org_mismatch, feed_not_enabled and slice_not_assigned (403), invalid_request (400), not_found (404), payload_too_large (413), rate_limited (429) or server_error. Only POST /events is rate limited in the route: 600 requests a minute per org and client.

Trend feed#

Contract 0.5.0 adds the shared social trend dataset (ADR 0061): one sync in MSO Cloud, read by every org that holds the feed. All four routes need platform:social.read and a path org equal to the token org. The reader resolves the org's entitlement from the written plugin row before any shared row is read (see Tenancy and security).

Route Query Answer
GET /orgs/{id}/social/trend-feed none enabled, topics (assigned), offered_topics, slices the org may read (empty when enabled is false, still 200), dataset { revision, as_of, last_check_at, origin }
GET /orgs/{id}/social/trend-feed/items slice: general or an assigned topic token slice, revision, items[]: vendor_id, name, passion_point, status, is_new, detected_at, roll_out_days, buzz, engagements, posts, unique_audience, sentiment, ranking_date, periods per window, sample_posts, keywords, origin, timestamps
GET /orgs/{id}/social/trend-feed/history window: 24h, 7d or 30d window, revision, rows[]: cycle_at, vendor_id, rank, name, status, buzz, engagements, posts, unique_audience, sentiment, origin; general list only
GET /orgs/{id}/social/trend-feed/search keyword, 1 to 80 characters keyword, cached, fetched_at, results[] of vendor_id, name, passion_point, buzz, engagements and optional figures
  • Normalised values. The reader serves a sentiment outside -1 to 1 as null and cuts sample-post text and keywords on code points, so every answer satisfies the contract.
  • No pagination. A slice or window is one consistent read of at most 5,000 rows (limits). A reader never holds a mix of two revisions.
  • Revision and ETag. revision is a counter raised with every change a reader can see. items and history send it as ETag ("42") and answer 304 to a matching If-None-Match. The route checks the token org, the entitlement and the slice first and evaluates If-None-Match after them, so a 304 is never an authorization. Responses stay Cache-Control: no-store.
  • 403 codes. feed_not_enabled when the org does not hold the feed (items, history and search; the state route answers 200 with enabled: false). slice_not_assigned for a topic the org was not assigned.
  • Search. The vendor answer passes the spam screen and stored review decisions, is cached for 6 hours and coalesces identical searches in flight. A limit per org answers 429 rate_limited with Retry-After; an unreachable vendor answers 502 or 503 server_error.
  • Event. When the revision is ahead of the announced one, the worker writes one trends.updated per org that holds the feed, with feed_revision in data. A lost webhook delays an app by at most its hourly reconciliation.
  • Deprecated. GET /social/trends and /social/trends/counts keep answering from the org's own ranking rows until 1.0.

A client keeps a local projection and replaces a slice or window in one transaction, only when the answer's revision is higher than the stored one; see App family and identity hub.

Events#

Events: outbox out, idempotent inMSO to appDomain changeMember added, app toggled,user disabled, trends loadedone org transactionplatform_outboxOne pending row per activesubscription; same event idcommits with the changeno subscription = no rowWorker sweep (60 s)Claim 10 rows per orgFOR UPDATE SKIP LOCKED2-minute lease, attempts + 1POST to the appX-MSO-Signature: sha256=hexX-MSO-Event-Id8 s timeout, no redirects2xx: deliveredRow settled408, 425, 429, 5xx: retryDelay 30 s x 2^(n-1), cap 6 hDead after 10 attemptsOther status: dead3xx, 4xx, inactive subscription,host not the app's own hostApp to MSOPOST /api/platform/v1/eventscontent.published onlyscope platform:events.write64 KB cap, 600 per minplatform_outbox (direction in)Unique per org and event idRepeat returns 202 duplicate: truebrand_id must belong to the orgNo consumer todayStored for lineage; nothing reads itConnectors pull performanceApp never pushes numbers
Outbound events are written with the change that caused them. Inbound events are deduplicated by event id.

Every event is one JSON envelope: id (also the idempotency key), type, org_id, occurred_at and data.

Event Direction data Written when
org.app.changed MSO to app app_id, status, plan, valid_to An admin changes the app for the org
membership.changed MSO to app user_id, change (added, updated, removed), role, brand_ids A membership changes
user.disabled MSO to app user_id A user is disabled
trends.updated MSO to app brand_id, through (date), optional feed_revision New trend rows land, or the shared feed's revision moved
content.published App to MSO asset_id, channel_post_id, brand_id, campaign_id, channel The app publishes a creative; stored for lineage, no consumer today

Signing, retries and idempotency#

  • Signature. X-MSO-Signature: sha256=<hex>, an HMAC-SHA256 of the exact raw body with the subscription secret. A receiver compares in constant time before parsing. The signature covers the body only, so replay protection is the event id.
  • Idempotency. X-MSO-Event-Id equals the envelope id. Delivery is at-least-once and a retry can arrive after a later event; a receiver stores seen ids and orders by occurred_at. The inbound side does the same: one row per org and event id, and a repeat answers duplicate: true.
  • Retries. 2xx settles the row. 408, 425, 429 and 5xx retry after 30 s x 2^(n-1), capped at 6 h, for at most 10 attempts. Any other status, including a redirect, is dead; a dead row stays in the table for inspection.
  • Destination. The subscription URL must be https on the satellite's own launch host, with no credentials in the URL and no loopback, private, link-local or metadata address. Redirects are never followed. Secrets are envelope-encrypted.
  • Atomicity. The outbox row commits or rolls back with the change that produced it, so a rolled-back change sends nothing.

Where it stops#

  • The API exposes only the third-party market-intelligence plane to apps; marketplace and marketing data have no endpoint.
  • The trend feed serves only orgs that hold the feed. Whether the vendor's terms allow redistribution is an open contract question (ADR 0061).
  • Subscription rows are not created by any screen or API in this repository.
  • Which organizations and apps use these endpoints today is on Project status.