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.
Loading runtime target…
Loading runtime target…
SAFE, SERVER-PROXIED TEST
Run the complete API cycle here
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.
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.
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
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.
Owns the local session, verified subject, correlation references, idempotency keys, service-account secret, and API calls.
Authorizes a maximum point amount and atomically applies one terminal accounting effect.
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.
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.
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"
}
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
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", ... }
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.
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.
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
}
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
Persist before sending. Generate the idempotency key once and store it with the exact request body.
Retry the same operation unchanged. Reuse
both key and payload after a disconnect, timeout/
408, 429, or 5xx.
Never recycle a key. The same key with a
different payload returns 409 Conflict.
Treat replay as success.
X-SounDiva-Idempotency-Replayed: true means the
original committed response was returned.
Refresh provider authentication. On an expired token, obtain a new token and retry with the original operation key.
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."
}
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
sessionBudgetPointsas 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.