Connect your game to weBump

Games define their own private JSON saves and reviewed public fields. These steps apply to the real API. The separate API reference offers fictional requests for exploring the contract.

1. Apply for a project

Verify your email in the console and provide your game name, description, icon, HTTPS launch URL, privacy and support pages, exact HTTPS callback, requested permissions and public field definitions. Verify the provided DNS TXT record. Approval provisions a public OAuth client ID. No shared game API key is needed.

2. Keep the security boundary on the server

A browser or Godot web export is downloadable. API URLs and client IDs are public; installation secrets, server keys and delegated player tokens must never be bundled into game files. Use a same-origin backend for OAuth sessions and player-scoped API calls. Keep access and refresh tokens encrypted server-side, with only a Secure, HttpOnly browser session cookie. Require exact-origin and CSRF checks for writes. Never turn the backend into an unauthenticated proxy for a privileged account.

3. Ask the player to connect

Generate fresh state and a PKCE S256 verifier/challenge on the server. Send the player to GET /oauth/authorize with client_id, response_type=code, scope, state, code_challenge, code_challenge_method=S256 and the exact registered redirect_uri. The player approves in weBump. At the callback, reject duplicate parameters, verify state once, and exchange the code with POST /oauth/token using grant_type=authorization_code, client_id, redirect_uri and code_verifier. Keep the resulting tokens on the server. Serialize refresh-token use; do not retry a consumed refresh token.

Start this flow in the same browser on an iPhone with a supporting weBump app. Cross-device desktop pairing remains separate work. Anyone can load a public game; accessing a real player's profile, visitors or server save still requires that player's consent.

4. Save game-defined JSON

{"inventory":[{"item":"seed","quantity":3}],
 "world":{"region":"meadow","unlocked":[1,2,5]},
 "settings":{"sound":true}}

GET /v1/me/state returns your private data and an ETag. PUT /v1/me/state/progress with {"value":...} and If-Match writes a named key. State allows up to 16 keys and 16 KiB total, including nested objects, arrays, strings, numbers, booleans and null. It is not a fixed high-score schema. Keep the primary save locally; this storage supplements it.

The revision is shared across state, capsule and showcase writes. Preserve it through your web backend. On 409, fetch current data and merge deliberately without discarding the local draft. Retry safe reads with bounded backoff and jitter; respect Retry-After. Do not blindly retry writes or refresh tokens.

5. Show a public game card

Request game.showcase and declare up to five reviewed fields. Fields may be bounded integers, booleans or reviewed enum values, with developer-defined labels:

{"capsule":{},"showcase":{
 "flowers":{"label":"Flowers grown","type":"integer","min":0,"max":1000000},
 "season":{"label":"Season","type":"enum","values":["spring","summer"]}}}

PUT /v1/me/showcase with {"value":{...}} and the current If-Match. The player decides whether to enable Show on my profile. Everyone viewing that profile can then see the approved game icon, title, selected fields and launch link. Private saves remain private. New reviewed games require no iOS update.

Upload a square static PNG, 128–512 pixels, RGB/RGBA, at most 128 KB. Assets, labels and links are reviewed with the application. Icons are served by weBump rather than developer tracking URLs.

6. Receive visitors

With visitors.receive, POST /v1/me/visitor-handoff using action=begin, client_id, response_type=code, scope=visitors.receive, the registered redirect_uri, fresh state, and a PKCE S256 challenge. Open the returned authorization_url. After verifying callback state, redeem the code through the same endpoint with action=redeem, code, redirect_uri and code_verifier, authenticated with the player's access token.

References are temporary and project-scoped. Recheck cards through GET /v1/me/visitors/{reference}; expired, delayed, blocked or withdrawn cards are unavailable. Keep reward deduplication alongside the local save and commit the reward and processed reference atomically. Remove cached personal data when access is withdrawn. The API reference's synthetic action=simulate is not a production operation.

7. Disconnect and release

POST /oauth/revoke with client_id and the player's token to revoke access. A player can also disconnect or delete game data in weBump. Test consent cancellation, invalid state, code replay, concurrent refresh, save conflicts, disconnect, hiding public cards and withdrawn visitors on real devices before release.

Interactive API reference · Connect button guidelines · Exports and departure · Swift SDK