What's Changing?#
The week of July 6, 2026, the default self-hosted Supabase configuration for API_EXTERNAL_URL will change to include the /auth/v1 path prefix:
API_EXTERNAL_URLwill default tohttp://localhost:8000/auth/v1(previouslyhttp://localhost:8000)GOTRUE_JWT_ISSUERindocker-compose.ymlwill change to${API_EXTERNAL_URL}(the actual URL will stay unchanged)- OAuth redirect configuration placeholders in
docker-compose.ymlwill become${API_EXTERNAL_URL}/callback - The API gateway routes for SAML SSO move from
/sso/saml/*to/auth/v1/sso/saml/*, so SAML ACS and metadata endpoints become…/auth/v1/sso/saml/acsand…/auth/v1/sso/saml/metadata
This aligns self-hosted Supabase with the platform behavior, and the CLI.
Why?#
- Consistency across deployments.
API_EXTERNAL_URLbehaves identically on platform, self-hosted, and CLI. - Custom OAuth providers work out of the box. GoTrue builds custom-provider callback URLs as
API_EXTERNAL_URL + /callback. With the prefix now in the base URL, that resolves to…/auth/v1/callbackand matches the existing API gateway route. - SAML aligns with the
/auth/v1convention used by every other auth endpoint, rather than living at a bare/sso/saml/*path. - The docs become accurate. The guidance that "your callback URL is built from
API_EXTERNAL_URL" is now literally true, instead of relying on the/auth/v1prefix being manually prepended in the compose file.
Am I Affected?#
You are affected if you run self-hosted Supabase from the ./docker directory and pull updates from master, and any of the following apply:
- You've overridden
API_EXTERNAL_URLin your.env(e.g.https://my-domain.com) - you'll need to change it tohttps://my-domain.com/auth/v1. - You maintain a customized
docker-compose.ymlwith OAuth providers - the redirect URIs change from${API_EXTERNAL_URL}/auth/v1/callbackto${API_EXTERNAL_URL}/callbackto avoid a doubled/auth/v1prefix. - You use SAML SSO - your IdP points at the old
/sso/saml/*endpoints and must be updated to/auth/v1/sso/saml/*. This is the main breaking case.
You are not affected if you:
- Use the Supabase platform
- Have OAuth providers registered with Google/GitHub/etc. - the final callback URL is unchanged (
…/auth/v1/callback), so no re-registration in the provider's developer console is needed - Don't use SAML SSO and pull the new
docker-compose.ymland.env.exampletogether without local changes - the defaults stay consistent
What Should I Do?#
If you pull the updated docker-compose.yml and .env.example together with no customizations, no action is required unless you use SAML SSO.
If you've customized API_EXTERNAL_URL:
- Append
/auth/v1to your value (e.g.https://my-domain.com→https://my-domain.com/auth/v1) - If your override file sets OAuth redirect URIs, change them from
${API_EXTERNAL_URL}/auth/v1/callbackto${API_EXTERNAL_URL}/callback - Restart the stack
If you use SAML SSO:
- Pull the updated
docker-compose.yml(or update your Kong and Envoy routes to/auth/v1/sso/saml/acsand/auth/v1/sso/saml/metadata) - Restart the stack
- Re-fetch your service provider metadata from
{API_EXTERNAL_URL}/auth/v1/sso/saml/metadataand update your IdP (ACS URL, SP entity ID) with the new endpoints - See the self-hosted SAML SSO guide
If you'd rather defer: keep your existing API_EXTERNAL_URL without the /auth/v1 suffix and retain your current OAuth/SAML configuration. This is a default change, not a removal - but we recommend aligning soon, since custom OAuth providers won't work without it.
Rollout#
| Date | Change |
|---|---|
| 2026-06-18 | This changelog published |
| 2026-07-06...10 | Updated self-hosting OAuth and SAML SSO docs published |
| 2026-07-06...10 | Default change ships in the next self-hosted Supabase release |