Party A API Integration Guide

Overview

This integration lets a logged-in Party A member enter the game lobby without a lobby username or password.

Party A sends the member's browser to the lobby with a short-lived tmp_code. The middleware verifies that code by calling Party A's getLoginID API from the server side.

Values To Exchange

Do not send real user traffic until both sides complete the canary checklist.

Browser Redirect

After the user is authenticated on Party A, Party A creates a single-use tmp_code and redirects the browser to the production lobby:

https://launchqa.click/?partner=<PARTNER_SLUG>&tmp_code=<URL_ENCODED_TMP_CODE>

Example

HTTP/1.1 302 Found
Location: https://launchqa.click/?partner=party-a-prod&tmp_code=SX5D8KRLUQv7aecGUxbxGn

• tmp_code must be random/unpredictable.
• tmp_code must be single-use.
• Recommended TTL is 5 minutes or less.
• It must identify exactly one currently authenticated Party A member.
• It must not contain PII or reusable credentials.
• It must be rejected by Party A after successful exchange.

Party A Server API

The middleware verifies tmp_code by calling Party A server-to-server.

POST <PARTY_A_API_BASE_URL>/v1/auth/getLoginID
Content-Type: application/json
X-Auth-Token: <X_AUTH_TOKEN>

{
  "tmp_code": "SX5D8KRLUQv7aecGUxbxGn"
}

Current middleware timeout: 10 seconds.

Success Response

{
  "message": "Success",
  "result_code": 200,
  "user_id": "900000001"
}

• user_id may be a string or number.
• user_id must be stable for the same Party A member.
• user_id must never be recycled to a different member.
• user_id must be non-empty.
• user_id should not expose unnecessary personal information.

Failure Responses

For expired codes, include the word expired or expire in message until both sides agree on a dedicated result code.

User Flow

Middleware API Reference

These endpoints are normally called by our lobby frontend after the browser redirect. Party A generally only needs the redirect contract and getLoginID API above.

POST /api/entry/party-a

{
  "partner": "party-a-prod",
  "tmpCode": "SX5D8KRLUQv7aecGUxbxGn"
}

Returning-user response

{
  "status": "authenticated",
  "session": {
    "authenticated": true,
    "userId": "usr_xxx",
    "username": "pa***********",
    "accountState": "active",
    "wsdAccountMasked": "wsd***001"
  },
  "mapping": "existing"
}

First-time-user response

{
  "status": "captcha_required",
  "ticket": "ticket_xxx",
  "captcha": {
    "captchaId": "captcha_xxx",
    "imageDataUrl": "data:image/png;base64,...",
    "expiresAt": "2026-07-07T00:00:00.000Z"
  }
}

POST /api/entry/party-a/register

Called by our lobby after the user enters the WSD captcha.

{
  "ticket": "ticket_xxx",
  "captchaCode": "1234"
}

POST /api/entry/party-a/register/refresh

Called by our lobby when the user requests a fresh captcha.

{
  "ticket": "ticket_xxx"
}

Error Shape

{
  "code": "PARTY_A_CODE_EXPIRED",
  "message": "The entry code expired. Please return to Party A and try again.",
  "retryable": false,
  "requestId": "req_xxx"
}

Security Notes

• The browser only receives partner and tmp_code; it never receives the server-to-server token.
• The middleware never returns raw Party A user_id to the browser.
• The middleware stores the Party A user mapping server-side.
• The middleware generates WSD credentials internally and stores sensitive credential material encrypted.
• tmp_code, tokens, and raw WSD credentials must not be logged by either side.
• Production uses HTTPS for browser and server-to-server traffic.

Canary Test Plan

1. Party A creates one test member and redirects to the lobby with a fresh tmp_code.
2. First entry shows welcome screen, then one WSD captcha after Enjoy now.
3. User enters captcha manually.
4. Lobby opens.
5. Same Party A member enters again with a new tmp_code.
6. Lobby opens directly, with no captcha.
7. Expired tmp_code returns expired state.
8. Replayed tmp_code returns replay/invalid state.
9. Disabled partner slug is rejected.
10. Both sides confirm no duplicate WSD account or duplicate mapping was created.

Production Go-Live Checklist

• Final lobby URL confirmed as https://launchqa.click/.
• Final partner slug confirmed.
• Party A API base URL confirmed.
• X-Auth-Token ownership confirmed.
• Party A confirms tmp_code TTL, single-use behavior, and error messages.
• Party A confirms stable non-recycled user_id.
• IP allowlist complete, if Party A restricts server-to-server calls.
• One throwaway-member canary passes end to end.
• Real members remain disabled until both sides approve go-live.