Scoped Supabase tokens: limit what your app’s agent can change

Supabase has introduced scoped personal access tokens, providing developers with a way to limit what their app's agent can change. These tokens are created in the Supabase dashboard, allowing developers to select specific organizations, projects, and permissions. Unlike classic tokens, scoped tokens cannot grant more access than the user originally had.

When creating a scoped token, it's crucial to understand the operations the automation job will perform. Mapping these operations to the required permissions helps ensure that the token has only the necessary access. Each operation, such as linking a local repository to a project, reading project settings, changing database objects, or managing another platform resource, must be carefully considered.

Permissions cannot be edited after creation, so it's essential to choose the appropriate token form based on the workflow. Classic tokens carry the permissions of the account that created them, including current and future access. In contrast, scoped tokens are constrained to the resources and permissions selected at creation.

When setting an expiry for a scoped token, it's recommended to use a preset or a custom date up to one year. If a user loses access to a project, the scoped token will lose that access too. When storing the token, ensure it's not written in source code, terminal transcripts, issue comments, or logs. Instead, restrict access using a CI secret manager or the appropriate local secret store.

To avoid breaking existing builds, replace one consumer of the current token at a time with the scoped token. Thoroughly test both the expected access and expected denial outside the selected scope. Keep a rollback plan in place to revert to the original token if necessary. Finally, record which job owns each token, who can rotate it, and when it expires.