SSOUNDIVA PARTNER LAB
SANDBOX

PARTNER ACTIVITY INTEGRATION

Two ways to play.
One Points system.

Bonus and Winnings Points on NCG and tutorial games—open a session, play locally, settle with aggregate or source balances. Redacted trace of every public API call. Reference: partners.dev.soundiva.com.

PARTNER WEBSITE

This page represents your application. Browser actions call its same-origin backend; only the backend talks to SounDiva with provider credentials.

IMPLEMENTATION GUIDE

What to build, what to send, what to expect

The protocol supports games, sweepstakes, contests, quizzes, loyalty experiences, and other approved external activities. SounDiva—not the partner—selects every session budget.

Server-to-serverIdempotentAggregate resultNo balance read

LIVE RUNTIME TARGET

Try the Activity API with your credentials

This guide uses the exact Activity API base configured for the running sandbox. The endpoint URLs below are hydrated from the same runtime state used by the partner backend. The production base is https://activity-api.soundiva.com; do not substitute the website origin.

ACTIVITY API BASE URL Loading runtime target…
Current sandbox configuration
KEYCLOAK PROVIDER TOKEN URL Loading runtime target…
Independent machine-to-machine endpoint

SAFE, SERVER-PROXIED TEST

Run the complete API cycle here

NO TOKEN IN BROWSER

Enter the Keycloak service-account credentials issued to your provider. This page sends them once to its same-origin sandbox backend, which obtains the token from the configured Keycloak URL, opens a session at the separately configured Activity API, and completes it with 0 consumed and 0 awarded points. The unused budget is released. The browser receives only a sanitized step summary—never the provider token.

Provider credentials A confidential, service-account-only Keycloak client for your backend integration.
partnerSubject Identifies the connected member using the pairwise value from your server-side OIDC session.
activityId Selects the activity and policy approved for your provider.
Ready. No values are saved by this page.

Use this form only at https://partners.soundiva.com over HTTPS. Localhost HTTP is allowed only for local development. The request is fixed to the same-origin /api/try-it/run adapter; the Activity API base and Keycloak provider token URL cannot be entered or overridden here. The page does not write these values to local or session storage, and clears the client secret immediately after every attempt.

If an API result is uncertain, submit the same participant and activity again with valid credentials. The server retains and retries the exact pending request; it does not create a second session or switch a pending completion to cancellation. Recovery data lives in this portal process only. Resolve pending runs before restarting it.

CURL fallback: server terminal only—never browser code.

Run these commands only from a trusted backend host or local server terminal. Outside the official form above, never paste provider credentials or access tokens into browser DevTools, frontend JavaScript, a mobile app, or client-visible logs. Store the client secret in a secret manager and redact tokens from observability data.

Replace the three values marked YOUR_…, then enter your provider secret at the hidden terminal prompt. The partnerSubject must be the pairwise subject resolved by SounDiva for this logical partner, and the activityId must already be approved by SounDiva. Production provider tokens are obtained only from https://auth.soundiva.com/realms/soundiva/protocol/openid-connect/token. This example requires curl, jq and openssl.

Loading commands…

To abandon an unfinished activity, use cancel instead of completion for its open session:

Loading commands…

01 · SYSTEM BOUNDARIES

How the integration works

01Partner catalogMember selects a game
→
02Partner backendRequests access server-to-server
→
03SounDiva decisionDenied, or approved + hold
→
04Game iframeLocal play, then one Exit result
Embedded game

Only after approval, HTML is returned by the emulated partner backend with the playable game balance and runs in an iframe without same-origin privileges. It never receives a provider secret, access token, member subject, or writable point amount.

Partner backend

Owns the local session, verified subject, correlation references, idempotency keys, service-account secret, and API calls.

SounDiva

Authorizes a maximum point amount and atomically applies one terminal accounting effect.

The iframe sends intent; the backend sends money-like effects.

The partner page first sends only the selected catalog gameId to its backend. A successful SounDiva open response creates an opaque GET /partner-game/game_... URL; before that there is no iframe. The game channel can request only an allowlisted actionId, exit, cancel, or new. The parent validates the exact source window before calling its same-origin backend. The backend—not browser JavaScript—creates correlation and idempotency identifiers, issues a one-time commandId, validates each action against server-owned game state, deduplicates retries, and freezes actions during finalization. Local actions never call SounDiva: the backend calls Keycloak plus open before the iframe, and exactly one complete call when the member exits.

02 · MEMBER SIGN-IN

Use the existing SounDiva Sign-In SDK

The same <soundiva-sign-in> web component used by SounDiva applications opens your own backend's /api/auth/login. The shared server SDK redirects directly to Keycloak, using your dedicated interactive OIDC client. No SounDiva website or hosted Connect page is involved.

<script type="module"
  src="/assets/vendor/soundiva-sign-in.js"></script>
<soundiva-sign-in action="login" theme="dark"
  identity-mode="status"></soundiva-sign-in>
{
  "type": "soundiva-auth-success",
  "detail": { "action": "login", "status": "authenticated" }
}

The browser file is a generated bundle of @beetx/auth-web, not a sandbox-specific widget. Download https://partners.soundiva.com/assets/vendor/soundiva-sign-in.js from the deployed portal, or request the same artifact during onboarding. Serve a reviewed copy on your own origin. The artifact manifest records source and SHA-256; access to the private npm registry is not required for this distribution.

Two different Keycloak clients.

The interactive OIDC client uses Authorization Code + S256 PKCE and owns your callback. The provider service client uses client_credentials for Activity API calls. Never reuse the SounDiva web application's secret or give the interactive client Activity roles.

Issuer:   https://auth.soundiva.com/realms/soundiva
Login:    https://partners.soundiva.com/api/auth/login
Callback: https://partners.soundiva.com/api/auth/callback
Session:  https://partners.soundiva.com/api/auth/session
Backchannel logout:
          https://partners.soundiva.com/api/auth/backchannel-logout

The server SDK owns state, PKCE, token validation, encrypted HttpOnly cookies, refresh, popup completion and logout. @beetx/auth-next is used in Next.js applications; its /node adapter runs the same implementation in this Node HTTP sandbox. The partner does not run Redis; revocation is checked against SounDiva's authoritative service.

GET https://api.soundiva.com/api/partner-auth/me
Authorization: Bearer <interactive user access token>

EXPECT · 200
{
  "status": "authenticated",
  "partnerId": "partner_skillgames_sandbox",
  "partnerSubject": "sdpa_..."
}

SounDiva verifies the token's issuer, aud=partner-auth-api and the registered interactive client-to-provider mapping. It resolves the existing member and returns the same stable pairwise identity used by the Activity API. The browser cannot select a member or partner. The backend sees the OIDC subject as part of standard OIDC; it does not forward that subject to the game API. Profile/email scopes are not requested. Browser events and sandbox state contain no identity or tokens.

Sign-in is not permission to play: the partner backend must still request admission for each new game. Keycloak records the dedicated client for login attribution. Game and ledger evidence stay on SounDiva; arbitrary page clicks inside a partner website require separate instrumentation.

03 · AUTHORIZE THE ACTIVITY

Get a Keycloak service token, then open one session

Both calls originate from your backend, but they have different destinations. Keycloak authenticates the provider service; The OIDC identity endpoint separately identifies the member. The browser never chooses a point amount. Your backend sends only the approved activity, pairwise participant correlation, and your participation reference to the Activity API.

Service account and required token claims.

SounDiva provisions a confidential client with service accounts enabled and browser/end-user grants disabled. The RS256 token has aud: platform-activity-api and permissions in resource_access.platform-activity-api.roles: activity:open and activity:complete. activity:read is reserved and has no provider route in the current contract; do not request it unless SounDiva enables a future read surface. The edge verifies its signature and claims locally against Keycloak JWKS. The request names optional OAuth scopes; Keycloak maps approved scopes to these roles, and the edge authorizes from the roles rather than the plain scope claim.

POSTLoading runtime target…Provider authentication
Authorization: Basic <clientId:clientSecret>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
scope=activity:open activity:complete
{
  "access_token": "<server-only>",
  "token_type": "Bearer",
  "expires_in": 300
}
POST/api/v1/activity-sessionsAccess decision + atomic hold
Authorization: Bearer <provider access token>
Content-Type: application/json

{
  "activityId": "partner-activity:demo",
  "partnerSubject": "sdpa_<pairwise-subject>",
  "externalRef": "participation-123",
  "idempotencyKey": "open-<unique-id>"
}
{
  "sessionId": "asession_...",
  "activityId": "partner-activity:demo",
  "sessionBudgetPoints": 50000,
  "expiresAt": "...",
  "status": "open"
}
FieldMeaningRule
activityIdApproved activity identifierMax 128 chars / 512 UTF-8 bytes
partnerSubjectPairwise partner correlationRequired; backend only; max 256 / 512 bytes
externalRefYour evidence / participation referenceUnique per provider + activity; max 128 / 512
idempotencyKeyIdentity of this exact operationUnique and persisted; max 128 / 512
201 means “yes” and the hold already exists.

This route is both the eligibility decision and the hold; do not add a separate check that could race. SounDiva selects the budget from available points and the approved profile. Only one of the five business-denial codes below is “no”, creates no new hold, and returns a stable public { code, message } reason that your backend may pass to the member unchanged. A 201 exposes only sessionBudgetPoints, never the account or global balance. Use expiresAt to prevent play after the hold expires.

Other 4xx responses are validation, expiry, or idempotency outcomes. They are not access decisions and may require exact-request recovery.

HTTP 400  { "code": "insufficient_member_points", ... }
HTTP 404  { "code": "activity_not_available", ... }
HTTP 404  { "code": "partner_subject_not_linked", ... }
HTTP 409  { "code": "account_not_active", ... }
HTTP 409  { "code": "activity_session_limit_reached", ... }
Identifier limits are checked before storage.

activityId, externalRef, resultRef, idempotencyKey, and path sessionId allow 128 Unicode characters and 512 UTF-8 bytes. partnerSubject allows 256 characters and 512 bytes. They must be well-formed Unicode without control characters. Any violation returns 400.

04 · PARTNER-OWNED PROCESS

Run any number of internal events

Play steps, quiz answers, prize reveals, contest transitions, and other activity events remain in your system. You do not send one SounDiva transaction per event.

Partner event 1local
Partner event 2local
Partner event Nlocal
→
One final aggregateAPI
Point calculation belongs to your backend.

The member browser may submit an action identifier, never a point delta or final counters. Your backend applies its rule version, stores the resulting evidence, and is the only component that sends the aggregate to SounDiva.

Keep evidence even when calls are aggregated.

Store your internal event IDs, timestamps, rule version, outcome source, and externalRef so an aggregate result can be reconstructed during audit or abuse review.

05 · ONE TERMINAL EFFECT

Complete the aggregate result or cancel

When the member presses Exit, your backend derives and sends exactly one aggregate completion. For a game bankroll, normalize the local net result: a loss sets only consumedPoints, a win sets only awardedPoints, and no change is 0 / 0. The generic activity contract also permits independent positive counters when a non-game activity genuinely consumes and awards points. Cancellation is only for an unfinished activity.

Authorization: Bearer <provider access token>
Content-Type: application/json
POST/api/v1/activity-sessions/{sessionId}/completeAtomic terminal result
{
  "consumedPoints": 0,
  "awardedPoints": 150,
  "resultRef": "partner-result-123",
  "idempotencyKey": "complete-<unique-id>"
}
{
  "sessionId": "asession_...",
  "status": "completed",
  "consumedPoints": 0,
  "awardedPoints": 150,
  "releasedPoints": 50000
}
The two counters are independent.

consumedPoints may not exceed the session budget; awardedPoints may not exceed the profile award cap. resultRef links the aggregate to your local evidence, is globally unique per provider, and has the same 128-character / 512-byte bound. Reusing either correlation in its scope returns 409. Unused budget is released atomically.

POST/api/v1/activity-sessions/{sessionId}/cancelCancel an unfinished session
Authorization: Bearer <provider access token>
Content-Type: application/json

{ "idempotencyKey": "cancel-<unique-id>" }
{
  "sessionId": "asession_...",
  "status": "cancelled"
}

Cancellation releases the entire unused budget without a points effect.

06 · OPERATIONS

Retries, idempotency, and failures

01

Persist before sending. Generate the idempotency key once and store it with the exact request body.

02

Retry the same operation unchanged. Reuse both key and payload after a disconnect, timeout/ 408, 429, or 5xx.

03

Never recycle a key. The same key with a different payload returns 409 Conflict.

04

Treat replay as success. X-SounDiva-Idempotency-Replayed: true means the original committed response was returned.

05

Refresh provider authentication. On an expired token, obtain a new token and retry with the original operation key.

06

Stop on authoritative expiry. HTTP 400 with activity_session_expired is not transient. For a late open retry, clear that attempt and start with a new externalRef and key. For complete or cancel, mark the session expired, clear the pending terminal operation, and do not retry it.

{
  "code": "activity_session_expired",
  "message": "The activity session is expired."
}
400 invalid input / insufficient points / authoritative expiry 401 invalid or expired provider token 403 missing activity service-account role 404 member or provider session not found 409 idempotency or terminal-state conflict 408 / 429 / 5xx retry unchanged

07 · READY TO INTEGRATE

Partner checklist

  • Mount the shared SounDiva auth SDK on your backend.
  • Render the official <soundiva-sign-in> browser component.
  • Keep identity correlation, secrets, and access tokens server-side.
  • Use the service-account-only Keycloak client issued by SounDiva and verify it has the required Activity API roles.
  • Persist externalRef, session IDs, idempotency keys, and internal evidence.
  • Open one session without sending an amount; use the returned sessionBudgetPoints as the consumption ceiling.
  • Aggregate internal events and send exactly one terminal outcome.
  • Implement unchanged retry and explicit cancellation.
  • Pass all contract tests before production credentials are enabled.

ACTIVITY CONTRACT CERTIFICATION

Sixteen required scenarios

The suite uses the same public provider contract and retains redacted evidence for tokens, server-selected budgets, aggregate completion, retries, scopes, and correlation references.