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.
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:/ |
| Organization | Exactly one org_ claim; a path organization that differs gets org_ |
| Lifetime | 600 s at most |
| Required claims | exp, iat, jti, sub, client_ |
| Scope | Plane it opens | Used by |
|---|---|---|
platform:orgs. |
Org structure: caller, launcher tiles, members, brands | me, me/, members, brands |
platform:entitlements. |
App entitlements of the org | entitlements |
platform:social. |
Third-party market-intelligence plane: social trends | social/ (four routes), social/, social/ |
platform:events. |
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 / |
orgs.read | The user, every org membership (not capped), active org and brand, super_ |
GET / |
orgs.read | One tile per app for the active org: app_, name, launch_, state enabled, not_ or expired |
GET / |
orgs.read | user_, email, name, role, brand_, disabled |
GET / |
orgs.read | id, slug, name |
GET / |
entitlements.read | Per app: plan, limits, valid_, status (active, trial, suspended, expired) |
GET / |
social.read | The org's feed grant and the dataset state; see Trend feed |
GET / |
social.read | Every usable row of one slice, with its revision |
GET / |
social.read | Every retained history row of one window, with its revision |
GET / |
social.read | The vendor's keyword search, proxied and cached |
GET / |
social.read | Deprecated since 0.5.0, removed in 1.0. Hourly ranking snapshots: keyword, platform, observed_, mentions, engagement; filters brand_, from, to |
GET / |
social.read | Deprecated with the route above. Daily row counts of the same rows, for reconciliation; window of 366 days at most |
POST / |
events.write | 202 {event_ for a content. 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 / |
none | enabled, topics (assigned), offered_, slices the org may read (empty when enabled is false, still 200), dataset { revision, as_ |
GET / |
slice: general or an assigned topic token |
slice, revision, items[]: vendor_, name, passion_, status, is_, detected_, roll_, buzz, engagements, posts, unique_, sentiment, ranking_, periods per window, sample_, keywords, origin, timestamps |
GET / |
window: 24h, 7d or 30d |
window, revision, rows[]: cycle_, vendor_, rank, name, status, buzz, engagements, posts, unique_, sentiment, origin; general list only |
GET / |
keyword, 1 to 80 characters |
keyword, cached, fetched_, results[] of vendor_, name, passion_, buzz, engagements and optional figures |
- Normalised values. The reader serves a sentiment outside -1 to 1 as
nulland 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.
revisionis a counter raised with every change a reader can see.itemsandhistorysend it asETag("42") and answer304to a matchingIf-None-Match. The route checks the token org, the entitlement and the slice first and evaluatesIf-None-Matchafter them, so a 304 is never an authorization. Responses stayCache-Control: no-store. - 403 codes.
feed_not_enabledwhen the org does not hold the feed (items, history and search; the state route answers 200 withenabled: false).slice_not_assignedfor 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_limitedwithRetry-After; an unreachable vendor answers 502 or 503server_error. - Event. When the revision is ahead of the announced one, the worker writes one
trends.updatedper org that holds the feed, withfeed_revisionindata. A lost webhook delays an app by at most its hourly reconciliation. - Deprecated.
GET /social/trendsand/social/trends/countskeep 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#
Every event is one JSON envelope: id (also the idempotency key), type, org_id, occurred_at and data.
| Event | Direction | data |
Written when |
|---|---|---|---|
org. |
MSO to app | app_, status, plan, valid_ |
An admin changes the app for the org |
membership. |
MSO to app | user_, change (added, updated, removed), role, brand_ |
A membership changes |
user. |
MSO to app | user_ |
A user is disabled |
trends. |
MSO to app | brand_, through (date), optional feed_ |
New trend rows land, or the shared feed's revision moved |
content. |
App to MSO | asset_, channel_, brand_, campaign_, 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-Idequals the envelopeid. Delivery is at-least-once and a retry can arrive after a later event; a receiver stores seen ids and orders byoccurred_at. The inbound side does the same: one row per org and event id, and a repeat answersduplicate: 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.