Skip to content

Existing Data Synchronization Flow ​

1. Business Scenario & Task Objectives ​

1.1 Background ​

Game vendors (CP) have accumulated a large amount of existing data such as vendor qualifications, game information, and compliance qualifications on the platform application (APP)'s original game operation platform. To make it easier for game vendors to run platform application (APP) game business on the SUD OpenPaaS platform without re-entering all historical game information, we implement automated and secure synchronization of existing data through a standardized interface authorization and data-pulling mechanism. This reduces vendors' manual operation costs while ensuring the accuracy and compliance of data synchronization.

1.2 Business Scenario ​

During the migration of platform application (APP) existing game business to the SUD OpenPaaS platform, the core scenarios are:

  • When a game vendor first onboards the SUD OpenPaaS platform, they need to initiate an account linking request with the platform application (APP) via OAuth 2.0 and receive the vendor's authorization consent;
  • After authorization is granted, the SUD OpenPaaS platform automatically pulls the full set of existing data for that vendor on the platform application (APP) side, completing a seamless data migration from the "platform application (APP)'s original platform" to the "SUD OpenPaaS platform";
  • After the migration is complete, the vendor can manage the vendor information, game information, and compliance qualifications of games in a unified manner on the SUD OpenPaaS platform, without repeated maintenance.

1.3 Task Objectives ​

  1. Interface level: The platform application (APP) exposes standard authorization interfaces based on the OAuth 2.0 authorization code mode, as well as vendor/game data-pulling interfaces, for compliant invocation by the SUD OpenPaaS platform;
  2. Data level: After obtaining vendor consent through the OAuth 2.0 authorization flow, SUD securely pulls the full set of existing data for the corresponding developer on the platform application (APP) side, including:
    • Game vendor (developer) basic information and KYC qualification information;
    • Game list (including unique game identifiers, names, icons, and other basic information);
    • Individual game detail (including icon sets, descriptions, promotional videos/images, and other operational information);
    • Game KYC qualification information (including software copyright, publishing license, third-party authorization, and other compliance information);
    • Game ICP filing information (subject, managers, pre-approval, and supplementary materials);
  3. Business level: Complete the developer account mapping between the SUD OpenPaaS platform and the platform application (APP) platform, achieve automated synchronization of existing game data, and support one-stop operation for vendors on the SUD OpenPaaS platform.

For a concrete reference implementation, see: Hello OP Integration with SUD OpenPaaS Example.


2. Participating Roles ​

text
┌────────────────┐     ┌───────────────────────┐     ┌────────────────────┐
│  User Browser  │     │  SUD OpenPaaS          │     │ Platform APP       │
│  (User Agent)  │     │  OAuth2 Client         │     │ AS + RS             │
└────────────────┘     └───────────────────────┘     └────────────────────┘
RoleIdentityDescription
Game vendor (user)Individual / enterprise adminOwns both an APP developer account and a SUD OpenPaaS vendor account
SUD OpenPaaSOAuth2 ClientHolds client_id + client_secret; after vendor consent, calls APP data APIs on behalf of that vendor
Platform application (APP)Authorization Server + Resource ServerIssues tokens and provides vendor/game existing-data pull APIs

Key principles:

  • Vendor passwords are entered only on the APP login page and never pass through SUD OpenPaaS;
  • SUD only receives a one-time authorization code, then exchanges it server-side using client_secret;
  • Subsequent data pulls always use Authorization: Bearer {access_token}, and the token must identify the authorized vendor (e.g. cp_id / uid).

3. Business Flow Overview ​

3.1 Business Flow Diagram ​

3.2 Phases ​

PhaseNameWhenDescription
Phase 0Client registration (one-time)Before APP / SUD go liveRegister SUD as an OAuth2 Client on the APP side; store client_id / client_secret securely
Phase 1User authorization (Authorization Code)First bind per vendorBrowser redirects to APP login/consent; callback returns code
Phase 2Token exchangeAfter receiving codeSUD backend exchanges code + client_secret for access_token / refresh_token; vendor identity comes from the token claim or cp.queryDetail
Phase 3Existing data pullWhile token is validCall vendor/game APIs in order; persist data and account mapping
Phase 4Token refresh / unbindOn expiry or unbindRefresh via refresh_token; on unbind, revoke tokens and clear mapping

4. Business Flow Description ​

4.1 Phase 0: Register SUD as OAuth2 Client (One-time) ​

The platform application (APP) must support registering SUD OpenPaaS as a trusted third-party app (OAuth2 Client), including at least:

  • client_id / client_secret
  • Callback whitelist redirect_uri (must match later authorize requests exactly)
  • Authorization scope (limited to existing-data pull)
  • Grant types: at least authorization_code and refresh_token

This step is done once. All subsequent vendor binds reuse the same Client credentials.

4.2 Phase 1: Onboarding and Authorization Initiation ​

After basic onboarding on SUD OpenPaaS, the vendor requests “sync existing game data / bind APP developer account”. SUD assembles OAuth 2.0 parameters and 302-redirects the browser to the APP authorize endpoint (oauth.authorize):

text
GET {authorize_endpoint}
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={sud_callback}
  &scope={scopes}
  &state={random_state}

If the user is not logged in, the APP should first show its own login page (password, SMS, etc.), then proceed to consent.

Note: The authorize/login UI must be hosted on the APP domain. Vendor passwords and session cookies are invisible to SUD; SUD should only receive code and state in the final callback.

4.3 Phase 2: Authorization Code Callback and Token Exchange ​

After the user consents, the APP redirects the browser back to the SUD callback:

json
{redirect_uri}?code={AUTHORIZATION_CODE}&state={state}

SUD must:

  1. Verify state matches the value issued at authorize time (CSRF protection);
  2. Call oauth.accessToken from the server with authorization_code;
  3. Persist access_token / refresh_token; obtain the subject id from the token identity claim (e.g. uid) or a subsequent cp.queryDetail call, and map it to the current SUD vendor account.

Token exchange must happen server-side; client_secret must never be sent to the browser.

4.4 Phase 3: Automated Pulling of Existing Data ​

Using a valid access_token, SUD should pull in this order:

  1. cp.queryDetail — vendor basic info
  2. cp.queryKYC — vendor KYC
  3. game.queryList — game list (paginated)
  4. For each game in the list:

Results are cleaned, stored in SUD OpenPaaS, and shown to the vendor.

4.5 Phase 4: Account Mapping and Token Refresh ​

  • Account mapping: Bind APP-side cp_id to the SUD vendor account for later incremental sync and billing association.
  • Token refresh: When access_token expires, call oauth.refreshToken; if refresh_token also expires, guide the vendor to re-authorize.
  • Unbind: Preferably revoke tokens and clear account mapping plus cached credentials.

4.6 Exception Handling ​

ScenarioSuggested handling
Authorization failed / user deniedPrompt failure and guide re-authorization
state mismatchAbort; warn of possible security risk; require re-auth
access_token expiredAuto-refresh with refresh_token, then retry
refresh_token expiredPrompt “authorization expired”; guide full re-auth
Partial missing game/KYC dataMark missing items; ask vendor to verify APP source data

5. Interface Call Sequence Diagram ​


6. Key Security Design ​

ConcernMechanismDescription
Password never reaches SUDAuthorization Code flowUser types password only on APP pages; SUD only gets code
redirect_uri whitelistFixed at Client registrationCallback must match registered value exactly
One-time short-lived codeOAuth standardcode invalid after use; keep TTL short
Protect client_secretServer-side exchange onlyNever expose secret to the browser
state anti-CSRFGenerated and verified by SUDEnsure callback belongs to this user-initiated auth
Token identity isolationToken bound to vendor identityOnly the authorized vendor’s data may be accessed
Per-app revokerevoke (if supported)Unbind can revoke this Client’s tokens without affecting other APP sessions

7. List of Involved Interfaces ​

The platform application (APP) must implement the following Webhooks (see Open APIs):

7.1 Authorization and Authentication (OAuth 2.0) ​

StepInterfaceDescription
1oauth.authorizeStart authorization; obtain code via browser
2oauth.accessTokenExchange code for access_token / refresh_token
3oauth.refreshTokenRefresh access_token

7.2 Existing Business Data Pull ​

StepInterfaceDescription
4cp.queryDetailQuery developer/vendor detail
5cp.queryKYCQuery developer KYC
6game.queryListQuery game list
7game.queryDetailQuery single game detail
8game.queryKYCQuery single game KYC
9game.queryICPQuery single game ICP filing
text
oauth.authorize
  → oauth.accessToken
    → cp.queryDetail
    → cp.queryKYC
    → game.queryList
      → (loop) game.queryDetail
      → (loop) game.queryKYC
      → (loop) game.queryICP
    → (when token near expiry) oauth.refreshToken