Swift iOS + Supabase: callback URL scheme and the ASWebAuthenticationSession return

Swift iOS + Supabase: callback URL scheme and the ASWebAuthenticationSession return

TL;DR

supabase-swift handles the token exchange, but iOS decides whether your app ever sees the callback. That decision lives in two places agents forget: the URL scheme in Info.plist and the Redirect URLs in the dashboard. Run on a real device, sign in with OAuth, and confirm the browser dismisses back into the app with an active session.

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Steps

1. Choose a custom URL scheme for your app and register it under CFBundleURLTypes in Info.plist.

   Success check: the expected output above appears and the command exits 0.

2. Add the matching redirect URL to the dashboard auth Redirect URLs. The scheme must match exactly; a typo here fails silently with the browser stuck on a blank page.

   Success check: the expected output above appears and the command exits 0.

3. Start OAuth with ASWebAuthenticationSession (or the supabase-swift helper that wraps it) using your scheme as the callback. Confirm the callback handler exchanges the code for a session and stores it.
4. On first launch, treat the session as unknown until the client finishes loading it from the keychain. Do not flash the login screen for a stored session.
5. Observe auth state changes to drive the root view switch (logged in vs logged out) rather than checking once in onAppear.

Compatibility

Tool: Supabase. The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Details

Swift iOS + Supabase: closing the OAuth return loop

Quick test

If Safari stays open on a success page, the scheme or redirect URL is wrong.

Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/auth/native-mobile-deep-linking