diff --git a/apps/docs/content/guides/deployment/branching/troubleshooting.mdx b/apps/docs/content/guides/deployment/branching/troubleshooting.mdx
index 1fd9194c40c..9a491563bc7 100644
--- a/apps/docs/content/guides/deployment/branching/troubleshooting.mdx
+++ b/apps/docs/content/guides/deployment/branching/troubleshooting.mdx
@@ -69,6 +69,12 @@ supabase db reset
# Navigate to Branches > Your Branch > View Logs
```
+### Permission denied errors on a new branch
+
+If the Data API returns `42501` permission denied errors on a branch for tables or functions that work on your base project, the branch is missing default privileges on the `public` schema. New branches are created without them, and only your migrations can grant them back.
+
+Check whether your initial migration contains `alter default privileges ... grant` statements for the `public` schema. If it doesn't, see [Default privileges on branches](/docs/guides/deployment/branching/working-with-branches#default-privileges-on-branches) for how to add them, or [grant access explicitly](/docs/guides/api/securing-your-api#grant-access-explicitly) in a migration.
+
### Migration order problems
Migrations must run in the correct order. Common issues:
diff --git a/apps/docs/content/guides/deployment/branching/working-with-branches.mdx b/apps/docs/content/guides/deployment/branching/working-with-branches.mdx
index c007f17cf5f..2ba6d9c4118 100644
--- a/apps/docs/content/guides/deployment/branching/working-with-branches.mdx
+++ b/apps/docs/content/guides/deployment/branching/working-with-branches.mdx
@@ -183,6 +183,105 @@ Migrations are run in sequential order. Each migration builds upon the previous
The preview branch inherits the migration history of your base project, so it only applies migrations that haven't been run yet. This can create an issue when rolling back migrations.
+### Default privileges on branches
+
+New branches are secure by default. They are created without [default privileges](/docs/guides/api/securing-your-api#default-privileges) on the `public` schema, regardless of the setting on your base project. New tables, functions, and sequences on a branch require explicit grants before `anon`, `authenticated`, or `service_role` can reach them through the Data API.
+
+Your migrations control whether a branch re-enables these privileges. If your base project has default privileges enabled and your migration history was initialized by Supabase Branching or the Supabase CLI, the initial migration already contains the `alter default privileges` statements that grant access on `public`. Running it on a new branch restores the same access your base project has, so no changes are needed.
+
+Two cases require manual intervention:
+
+- You manage migrations outside Supabase and want to [keep default privileges enabled](#keep-default-privileges-enabled) on branches.
+- You use Supabase managed migrations and want to [revoke default privileges](#revoke-default-privileges) on your base project and branches.
+
+#### Keep default privileges enabled
+
+If your migration history was not initialized by Supabase Branching or the Supabase CLI, your initial migration doesn't grant default privileges, so new branches start without them. To restore the same access your base project has:
+
+
+
+
+
+ Open the [Data API settings](/dashboard/project/_/integrations/data_api/settings) in the Supabase Dashboard and turn on **Default privileges for new entities**.
+
+
+
+
+
+
+
+
+ Insert the following statements at the start of your initial migration file. Subsequent migrations then inherit these privileges, so the final database state is unchanged.
+
+ ```sql
+ alter default privileges for role postgres in schema public grant usage, select, update on sequences to anon, authenticated, service_role;
+ alter default privileges for role postgres in schema public grant execute on functions to anon, authenticated, service_role;
+ alter default privileges for role postgres in schema public grant select, insert, update, delete on tables to anon, authenticated, service_role;
+ ```
+
+
+
+
+
+
+
+
+ Mark the updated migration as applied so it isn't rerun on your base project. See [Diagnosing and fixing sync errors](/docs/guides/deployment/database-migrations#diagnosing-and-fixing-sync-errors).
+
+ ```bash
+ supabase migration repair --status applied
+ ```
+
+
+
+
+
+
+#### Revoke default privileges
+
+For improved security, we recommend not exposing the `public` schema automatically on your base project either. If your initial migration was generated by Supabase Branching or the Supabase CLI, it re-grants default privileges when it runs on a branch. To revoke them on your base project and branches:
+
+
+
+
+
+ Open the [Data API settings](/dashboard/project/_/integrations/data_api/settings) in the Supabase Dashboard and turn off **Default privileges for new entities**.
+
+
+
+
+
+
+
+
+ Create a new migration file with the Supabase CLI. Don't edit the initial migration, because that affects subsequent migrations in your history.
+
+ ```bash
+ supabase migration new revoke_default_privileges
+ ```
+
+ Add the following statements to the generated file:
+
+ ```sql
+ alter default privileges for role postgres in schema public revoke select, insert, update, delete on tables from anon, authenticated, service_role;
+ alter default privileges for role postgres in schema public revoke execute on functions from anon, authenticated, service_role, public;
+ alter default privileges for role postgres in schema public revoke usage, select, update on sequences from anon, authenticated, service_role;
+ ```
+
+
+
+
+
+
+
+
+ Commit the new migration file and push it to your Git repository. The migration runs on your base project when merged and on every new branch, so both start without default privileges.
+
+
+
+
+
+
### Using ORM or custom seed scripts
If you want to use your own ORM for managing migrations and seed scripts, you will need to run them in GitHub Actions after the preview branch is ready. The branch credentials can be fetched using the following example GHA workflow.