OAuth Scope Issues
OAuth scope errors happen when Stack2X doesn't have enough permissions to perform a specific action on your Supabase Cloud instance. This guide helps you identify and fix these issues quickly.
The "Insufficient Scopes" Error
What it looks like: "Insufficient scopes" or "Additional authorization required"
This is the most common OAuth error. It means Stack2X needs permissions that weren't granted when you first connected the instance. For example, you might have initially connected with read-only access but are now trying to restore a backup, which requires write access.
This isn't a bug -- it's by design. Stack2X requests only the minimum permissions needed at the time of connection, so you may need to grant additional scopes later as you use more features.
How to Re-Authorize with More Permissions
When you see an insufficient scopes error, Stack2X displays a clear message explaining what additional permissions are needed. To grant them:
- Click the Re-Authorize button in the error message, or go to the instance's settings page and click Update Permissions.
- You'll be redirected to Supabase, where you'll see the updated list of permissions Stack2X is requesting.
- Review the permissions and click Authorize.
- You'll be redirected back to Stack2X. The instance connection is updated automatically.
This process updates your existing connection -- it doesn't create a new one. Your backup history, migration records, and all other data remain untouched.
Scope Requirements by Component
Different Stack2X features need different levels of access:
| Feature | Required Scopes |
|---|---|
| View instance details | Read |
| Create backups | Read |
| Download backups | Read |
| Restore backups | Read + Write |
| Run migrations (source) | Read |
| Run migrations (target) | Read + Write |
| Update project settings | Read + Write + Admin |
If you're unsure which scopes you need, Stack2X tells you at the point of the error. You only need to authorize the level required for your current task.
Revoking and Reconnecting
If re-authorization doesn't resolve the issue, or if you want to start fresh, you can revoke Stack2X's access and reconnect:
- Log in to your Supabase account at supabase.com.
- Go to Account Settings and find the Authorized Applications section.
- Find Stack2X in the list and click Revoke.
- Back in Stack2X, go to the instance's settings and click Reconnect.
- Follow the OAuth flow again, granting the permissions you need.
This creates a new connection token. Your instance stays in Stack2X with all its history, but the OAuth link is rebuilt from scratch.
Still Having Trouble
If you've re-authorized and the error persists, check the following:
- Make sure you're authorizing with the same Supabase account that owns the project. If the project belongs to a Supabase organization, you may need an account with the right role in that organization.
- Verify that the Supabase project hasn't been paused or deleted.
- Contact Stack2X support if the issue continues -- there may be a temporary problem with the OAuth connection on Supabase's side.