Skip to main content

Quickstart

This walks you from a freshly provisioned tenant to posting and reading your first comment. It assumes your tenant already exists — the RSMG Engage team provisions tenants (see Overview).

1. Sign in and mint credentials​

  1. Your admin opens the invitation email and sets a password, landing in the admin console.
  2. Mint an API key (Console → API Keys → New). Copy the ek_… value — it's shown once. See Authentication.
  3. Mint an identity signing secret (Console → Identity → Mint). Copy it — also shown once. This flips your tenant into verify mode; see Identity signing.

Store both on your backend (environment variables / secret manager). Never expose them to a browser.

2. Post the first comment​

Discussions are lazy — posting to a content item by its external_id creates the discussion on the spot (its title defaults to the external_id). Send the API key and a signed identity assertion:

curl -X POST \
  "https://{slug}.rsmg-engage.com/api/v1/discussions/by-external/article-123/comments" \
  -H "X-API-Key: ek_your_key_here" \
  -H "X-RSMG-Engage-Identity: $ASSERTION" \
  -H "X-RSMG-Engage-Identity-Signature: t=$T,v1=$V1,kid=$KID" \
  -H "Content-Type: application/json" \
  -d '{"body": "First!"}'

{slug} is your tenant slug. The body.user_id field is ignored in verify mode — the acting user comes from the signed assertion, and the user is created automatically if it's their first action.

:::tip Getting a 403 IDENTITY_VERIFICATION_REQUIRED? That means the request reached a deployed tenant that has no signing secret yet (or you didn't attach the assertion). Mint the secret (step 1) and sign the request. A 401 instead means the assertion was attached but failed to verify — see the debug checklist. :::

3. Read the comments back​

curl "https://{slug}.rsmg-engage.com/api/v1/discussions/by-external/article-123/comments" \
  -H "X-API-Key: ek_your_key_here"

Before the first comment exists, this returns 404 (no discussion yet) — render an empty state. After step 2 it returns the comment you posted.

4. Go real-time (optional)​

To live-update the page, mint a short-lived stream ticket and open an SSE connection:

curl -X POST "https://{slug}.rsmg-engage.com/api/v1/stream/ticket-by-external" \
  -H "X-API-Key: ek_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"externalId": "article-123"}'
# → { "data": { "ticket": "...", "discussionId": "...", "expiresAt": "..." } }

Then connect to GET /api/v1/stream/{discussionId}?ticket=…. See Real-time (SSE).

Next​