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
- 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;
- 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);
- 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
┌────────────────┐ ┌───────────────────────┐ ┌────────────────────┐
│ User Browser │ │ SUD OpenPaaS │ │ Platform APP │
│ (User Agent) │ │ OAuth2 Client │ │ AS + RS │
└────────────────┘ └───────────────────────┘ └────────────────────┘| Role | Identity | Description |
|---|---|---|
| Game vendor (user) | Individual / enterprise admin | Owns both an APP developer account and a SUD OpenPaaS vendor account |
| SUD OpenPaaS | OAuth2 Client | Holds client_id + client_secret; after vendor consent, calls APP data APIs on behalf of that vendor |
| Platform application (APP) | Authorization Server + Resource Server | Issues 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 usingclient_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
| Phase | Name | When | Description |
|---|---|---|---|
| Phase 0 | Client registration (one-time) | Before APP / SUD go live | Register SUD as an OAuth2 Client on the APP side; store client_id / client_secret securely |
| Phase 1 | User authorization (Authorization Code) | First bind per vendor | Browser redirects to APP login/consent; callback returns code |
| Phase 2 | Token exchange | After receiving code | SUD backend exchanges code + client_secret for access_token / refresh_token; vendor identity comes from the token claim or cp.queryDetail |
| Phase 3 | Existing data pull | While token is valid | Call vendor/game APIs in order; persist data and account mapping |
| Phase 4 | Token refresh / unbind | On expiry or unbind | Refresh 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_codeandrefresh_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):
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
codeandstatein 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:
{redirect_uri}?code={AUTHORIZATION_CODE}&state={state}SUD must:
- Verify
statematches the value issued at authorize time (CSRF protection); - Call oauth.accessToken from the server with
authorization_code; - Persist
access_token/refresh_token; obtain the subjectidfrom 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:
- cp.queryDetail — vendor basic info
- cp.queryKYC — vendor KYC
- game.queryList — game list (paginated)
- 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_idto the SUD vendor account for later incremental sync and billing association. - Token refresh: When
access_tokenexpires, call oauth.refreshToken; ifrefresh_tokenalso expires, guide the vendor to re-authorize. - Unbind: Preferably revoke tokens and clear account mapping plus cached credentials.
4.6 Exception Handling
| Scenario | Suggested handling |
|---|---|
| Authorization failed / user denied | Prompt failure and guide re-authorization |
state mismatch | Abort; warn of possible security risk; require re-auth |
access_token expired | Auto-refresh with refresh_token, then retry |
refresh_token expired | Prompt “authorization expired”; guide full re-auth |
| Partial missing game/KYC data | Mark missing items; ask vendor to verify APP source data |
5. Interface Call Sequence Diagram
6. Key Security Design
| Concern | Mechanism | Description |
|---|---|---|
| Password never reaches SUD | Authorization Code flow | User types password only on APP pages; SUD only gets code |
redirect_uri whitelist | Fixed at Client registration | Callback must match registered value exactly |
| One-time short-lived code | OAuth standard | code invalid after use; keep TTL short |
Protect client_secret | Server-side exchange only | Never expose secret to the browser |
state anti-CSRF | Generated and verified by SUD | Ensure callback belongs to this user-initiated auth |
| Token identity isolation | Token bound to vendor identity | Only the authorized vendor’s data may be accessed |
| Per-app revoke | revoke (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)
| Step | Interface | Description |
|---|---|---|
| 1 | oauth.authorize | Start authorization; obtain code via browser |
| 2 | oauth.accessToken | Exchange code for access_token / refresh_token |
| 3 | oauth.refreshToken | Refresh access_token |
7.2 Existing Business Data Pull
| Step | Interface | Description |
|---|---|---|
| 4 | cp.queryDetail | Query developer/vendor detail |
| 5 | cp.queryKYC | Query developer KYC |
| 6 | game.queryList | Query game list |
| 7 | game.queryDetail | Query single game detail |
| 8 | game.queryKYC | Query single game KYC |
| 9 | game.queryICP | Query single game ICP filing |
7.3 Recommended Call Order
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