Fix self-hosted Supabase auth routes before SAML breaks

Supabase has confirmed a self-hosted auth configuration change for its next self-hosted release. Confidence level: confirmed for the changelog, limited until the updated self-hosting docs and release land. Teams running customized self-hosted Supabase setups should check API_EXTERNAL_URL, OAuth callback placeholders, and SAML SSO routes before upgrading.

Caption: Supabase's changelog is the primary source for the self-hosted API_EXTERNAL_URL and SAML route update. Source: Supabase.

What changed

Supabase says the default self-hosted API_EXTERNAL_URL will change during the week of July 6, 2026. The default moves from http://localhost:8000 to http://localhost:8000/auth/v1.

The practical breaking point is SAML SSO. Supabase says SAML routes move from /sso/saml/* to /auth/v1/sso/saml/*, which means ACS and metadata endpoints become /auth/v1/sso/saml/acs and /auth/v1/sso/saml/metadata.

Key takeaways

• Supabase is aligning self-hosted auth URLs with platform behavior and CLI expectations.
• The change is scheduled around the week of July 6, 2026, with docs updates expected in the same window.
• OAuth provider registrations may not need re-registration if the final callback URL remains unchanged.
• SAML users must update IdP ACS and metadata URLs if they point to the old /sso/saml/* paths.
• Teams that customized .env, docker-compose.yml, Kong, or Envoy should review the diff before pulling updates.

Availability and access

This is not a hosted Supabase dashboard feature to turn on. It affects self-hosted Supabase users who pull updates from the ./docker setup and rely on Supabase Auth routes.

Supabase says teams without SAML SSO and without local customization can pull the updated docker-compose.yml and .env.example together with no action. Customized setups need a manual check, especially where reverse proxies, OAuth providers, or SAML identity providers hard-code route paths.

Practical LinkLoot angle

Treat this as a pre-upgrade checklist, not a post-incident note. Before upgrading self-hosted Supabase, search your deployment for API_EXTERNAL_URL, /sso/saml, /auth/v1/callback, Kong route overrides, Envoy route overrides, and IdP metadata URLs.

If your team uses AI coding tools to maintain infrastructure files, add this route migration to your review checklist. LinkLoot's broader automation guide at /guides/ai-workflow-automation is useful here because infrastructure agents should verify routes and docs before committing generated config changes.

What to verify before you act

• Confirm whether your .env overrides API_EXTERNAL_URL; if yes, test appending /auth/v1.
• Check whether your OAuth config uses ${API_EXTERNAL_URL}/auth/v1/callback; Supabase says it should become ${API_EXTERNAL_URL}/callback after the base URL includes /auth/v1.
• If you use SAML SSO, update IdP ACS and metadata endpoints to /auth/v1/sso/saml/*.
• Pull updated docker-compose.yml and .env.example together in a staging environment before production.
• Re-fetch service provider metadata after the route change and run a full login test.

Source check

Confirmed by: Supabase's official changelog states the new API_EXTERNAL_URL default, the OAuth placeholder change, the SAML route movement, and the week-of-July-6 timing. It also identifies customized self-hosted deployments and SAML SSO as the main action areas.

Independent context: Releasebot's Supabase feed mirrors the same change in its June update timeline. Supabase's GitHub changelog discussion category provides the official community channel to watch for related follow-up discussions, but the article relies on the Supabase changelog for the factual claim.