iOS Game Auth Playbook:
Godot + Supabase

This is the most important section for understanding what actually happens on the device and server. Where does the session live? What happens when you close the app? What happens when you delete the app?

Where the session is stored

When Supabase's signInAnonymously() succeeds, it creates two things: a server-side record in auth.users and auth.sessions (on Supabase's Postgres), and a client-side token pair (access token JWT + refresh token string). The client library stores this token pair in whatever storage backend you configure. In a browser, that's localStorage by default. In Godot, you're using the supabase-community/godot-engine.supabase addon, which stores the tokens however you implement the storage adapter. For a mobile game, you should write the tokens to a file in the app's sandboxed data directory (e.g., user://auth_session.json in Godot's user:// path).

App lifecycle: close, reopen, kill, reboot

Refresh token behavior

Supabase refresh tokens never expire on their own but can only be used once. When you use a refresh token to get a new access token, Supabase issues a new refresh token and invalidates the old one. The client library handles this automatically via an onAuthStateChange listener that fires a TOKEN_REFRESHED event. You must persist the new token pair every time this event fires, or you'll end up with a stale refresh token that's already been consumed.

Sessions can be configured to have a maximum lifetime or inactivity timeout (Pro plan+), but by default, sessions are indefinite. A user who launches the game once a month will still have a valid session as long as the refresh token is intact on the device. If they don't launch for a very long time and you've configured an inactivity timeout, the session terminates server-side and the client gets an error on the next refresh attempt. For a game, don't set an inactivity timeout on anonymous sessions.

What "skip" means in the post-tutorial prompt

"Skip" means the user stays on their anonymous Supabase session with no linked identity provider. Their creatures and progress are stored server-side under their anonymous user_id, and the session tokens live in user:// on the device. They can play normally. The risk is: if they delete the app, lose their phone, or factory reset, their account is unrecoverable. They have no email, no Game Center ID, no Apple ID attached. There is no recovery path.

This is acceptable as a default state but you should make the risk clear to the user. The "Save your progress?" prompt should communicate: "Your creatures live on this device. If you lose this device or delete the app, they're gone forever. Sign in to protect them." Periodically re-prompt (e.g., when they create their 5th creature, or hit level 10, or after 3 days of play) if they're still anonymous.

Rate limiting and abuse prevention

Default 30 anonymous sign-ups per hour per IP. Enable CAPTCHA in Supabase dashboard. Use RLS policies like (auth.jwt()->>'is_anonymous')::boolean IS FALSE to gate premium features behind linked accounts.

Linking flow

When the user taps "Sign in with Apple" from the post-tutorial prompt, the anonymous user's UUID is preserved. Supabase's linkIdentity() attaches the Apple identity to the existing user record. All game data, progress, and creatures remain on the same user_id. The JWT's is_anonymous claim flips to false, and any RLS-gated features unlock immediately. No data migration, no UUID change, no server-side gymnastics.

const SESSION_PATH = "user://auth_session.json"

func _ready():
    # Listen for ALL auth state changes
    supabase.auth.on_auth_state_change.connect(_on_auth_change)

    # Try to restore existing session from disk
    var saved = _load_session_from_disk()
    if saved:
        await supabase.auth.set_session(saved.access_token, saved.refresh_token)
    else:
        # No saved session: first launch or reinstall
        await supabase.auth.sign_in_anonymously()

func _on_auth_change(event, session):
    if event in ["SIGNED_IN", "TOKEN_REFRESHED"]:
        # ALWAYS persist new tokens to disk immediately
        _save_session_to_disk(session)

func _save_session_to_disk(session):
    var file = FileAccess.open(SESSION_PATH, FileAccess.WRITE)
    file.store_string(JSON.stringify({
        "access_token": session.access_token,
        "refresh_token": session.refresh_token
    }))

func _load_session_from_disk():
    if not FileAccess.file_exists(SESSION_PATH):
        return null
    var file = FileAccess.open(SESSION_PATH, FileAccess.READ)
    return JSON.parse_string(file.get_as_text())

Game Center authentication is silent, signature-based, and not OAuth. It operates through GKLocalPlayer.local.authenticateHandler, a closure that iOS calls multiple times throughout the app lifecycle—on initial set, on auth state changes, and when the user switches accounts.

What happens on the device

If the user is signed into Game Center via iOS Settings (the default for any device with an Apple ID), the handler fires with isAuthenticated = true and a "Welcome back" banner slides from the top. No UI is presented. No user interaction. This is why Game Center is Tier 1 in the cascade.

If the user is not signed in, a login UIViewController is returned exactly once. If the user dismisses it, the app cannot show it again until the user signs in via Settings manually. This is an iOS-level restriction—there is no workaround.

Identity verification (the crypto handshake)

Game Center provides no JWT, no OAuth token, and no email address. Instead, it uses fetchItems(forIdentityVerificationSignature:) (iOS 13.5+), which returns five values:

Your server reconstructs the payload by concatenating teamPlayerID + bundleID + timestamp(bigEndian) + salt, fetches Apple's public certificate from publicKeyURL, and verifies the RSA-SHA256 signature. If it checks out, the user is who they say they are.

Player identifiers

teamPlayerID is persistent across all your games under the same Apple Developer team. gamePlayerID is scoped to a single game. Use teamPlayerID as your canonical identifier—it lets you recognize the same player across Bobium Brawlers and any future titles. Also available: displayName, alias, isUnderage, and isMultiplayerGamingRestricted.

Xcode setup

Add the Game Center capability in Signing & Capabilities. This sets the com.apple.developer.game-center entitlement and links GameKit.framework. No Info.plist modifications needed. Game Center must also be enabled in App Store Connect under your app's Services tab. That's it.

Game Center is not a built-in Supabase provider and can't be added through standard configuration (it's not OAuth/OIDC). The solution is a Supabase Edge Function that verifies Game Center signatures and creates/retrieves Supabase sessions.

User creation strategy

The Edge Function creates Supabase users with a synthetic email like gc_{teamPlayerId}@gamecenter.internal since Game Center provides no real email. The teamPlayerID goes into app_metadata for lookup on subsequent logins. Use admin.createUser({ email, email_confirm: true }) to skip verification, then admin.generateLink({ type: 'magiclink' }) to produce a session.

The client receives a standard Supabase JWT and uses it for all subsequent API calls. RLS works normally via auth.uid().

Linking anonymous sessions to Game Center

When Game Center succeeds during Phase 1, the user already has an anonymous Supabase session. Two approaches:

Option A (simpler): The Edge Function receives the anonymous user's JWT alongside the Game Center payload. It verifies the GC signature, then calls admin.updateUserById() on the existing anonymous user to set app_metadata.gc_team_player_id and flip is_anonymous to false. Same UUID, no data migration.

Option B (more standard): The Edge Function creates or finds the GC-linked user, returns a new session, and the client replaces its session. Downside: the anonymous user's data must be migrated to the new user ID. Option A is strongly recommended.

Sign in with Apple

Supabase supports Apple natively via signInWithIdToken(). The iOS flow uses Apple's AuthenticationServices framework: generate a nonce, request authorization via ASAuthorizationAppleIDProvider, pass the resulting identity token to Supabase. Apple provides an email (possibly a private relay address like abc@privaterelay.appleid.com) and the user's name only on first authorization—you must persist the name immediately.

Xcode requirement: Add the "Sign in with Apple" capability, which sets the com.apple.developer.applesignin entitlement.

GodotApplePlugins includes Sign in with Apple support, so the same plugin handles both Game Center and Apple Sign-In.

Google Sign-In

Google's iOS SDK presents a native bottom sheet where the user selects an account. Pass the resulting ID token to signInWithIdToken() with provider: 'google'. Configuration requires creating both a Web Application and iOS OAuth client in Google Cloud Console. The Web client ID and secret go into the Supabase dashboard; the iOS client ID enables native SDK auth.

Account linking

Supabase provides linkIdentity() for OAuth providers and updateUser() for email. Enable "Manual Linking" in the Supabase dashboard under Auth > Providers. When an anonymous user links an identity, their UUID is preserved—no data migration. The is_anonymous JWT claim flips to false automatically.

Plugin landscape

GodotApplePlugins is the clear first choice. It's built on SwiftGodot (the modern GDExtension Swift binding), maps 1:1 to Apple's GK*/AS* APIs using snake_case, and is maintained by Miguel de Icaza. Drop the binaries into addons/.

Signal flow for native auth

GDScript calls a plugin method → SwiftGodot bridges to Swift → Swift calls iOS API → iOS presents auth UI (if needed) → Swift receives callback → onComplete.callDeferred() returns data to GDScript.

Platform guards

iOS plugins return null in the Godot editor and on non-iOS platforms. Always guard with ClassDB.class_exists():

var _game_center: Variant = null

func _ready():
    # Always start with anonymous Supabase auth
    var session = await supabase.auth.sign_in_anonymously()
    _store_session(session)

    # Then attempt silent Game Center
    if ClassDB.class_exists("GameCenter"):
        _game_center = ClassDB.instantiate("GameCenter")
        _game_center.authenticate(_on_gc_auth)

func _on_gc_auth(error, player):
    if error == OK:
        # Get signature data for server verification
        var sig_data = await player.fetch_identity_verification_signature()
        # POST to Edge Function with sig + current anon JWT
        var result = await _call_edge_function(
            "gamecenter-auth", {
                "public_key_url": sig_data.public_key_url,
                "signature": sig_data.signature,
                "salt": sig_data.salt,
                "timestamp": sig_data.timestamp,
                "team_player_id": player.team_player_id,
                "anon_user_id": supabase.auth.current_user.id
            })
        if result.ok:
            _store_session(result.session)
    else:
        # Game Center unavailable. User stays anonymous.
        # Will be prompted post-tutorial.
        pass

All capabilities are added in Xcode under Signing & Capabilities. Godot's iOS export template respects the .entitlements file you configure. GodotApplePlugins documentation covers the exact file paths.

For Google Sign-In: add the reversed Google client ID as a URL scheme in your Info.plist (format: com.googleusercontent.apps.YOUR_CLIENT_ID). No entitlement needed.