Self-hosted Supabase: API_EXTERNAL_URL to include /auth/v1

[aantti]

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_URL will default to http://localhost:8000/auth/v1 (previously http://localhost:8000)
• GOTRUE_JWT_ISSUER in docker-compose.yml will change to ${API_EXTERNAL_URL} (the actual URL will stay unchanged)
• OAuth redirect configuration placeholders in docker-compose.yml will 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/acs and …/auth/v1/sso/saml/metadata

This aligns self-hosted Supabase with the platform behavior, and the CLI.

Why?

• Consistency across deployments. API_EXTERNAL_URL behaves 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/callback and matches the existing API gateway route.
• SAML aligns with the /auth/v1 convention 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/v1 prefix 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_URL in your .env (e.g. https://my-domain.com) - you'll need to change it to https://my-domain.com/auth/v1.
• You maintain a customized docker-compose.yml with OAuth providers - the redirect URIs change from ${API_EXTERNAL_URL}/auth/v1/callback to ${API_EXTERNAL_URL}/callback to avoid a doubled /auth/v1 prefix.
• 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.yml and .env.example together 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:

1. Append /auth/v1 to your value (e.g. https://my-domain.com → https://my-domain.com/auth/v1)
2. If your override file sets OAuth redirect URIs, change them from ${API_EXTERNAL_URL}/auth/v1/callback to ${API_EXTERNAL_URL}/callback
3. Restart the stack

If you use SAML SSO:

1. Pull the updated docker-compose.yml (or update your Kong and Envoy routes to /auth/v1/sso/saml/acs and /auth/v1/sso/saml/metadata)
2. Restart the stack
3. Re-fetch your service provider metadata from {API_EXTERNAL_URL}/auth/v1/sso/saml/metadata and update your IdP (ACS URL, SP entity ID) with the new endpoints
4. 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

[aantti]

See PR #47640