Who a call is made as

Every call to Supabase carries two things: the project's key (apikey) and a bearer token that says who calls. The repositories, Storage, Edge Functions and Realtime all ask one bean for them, SupabaseCredentials (the bean supabaseCredentials), so they always act as the same user.

Why

The database decides what a caller may read and write (row-level security), so the token on a call is what protects the data. If each part chose its own token, one of them would sooner or later send the wrong one: a user's call with the service role, or one user's call with another's token. One bean with one rule is checked once.

Example

@Service()
class Cleanup {
  Cleanup(this.credentials, this.todos);

  final SupabaseCredentials credentials;
  final Todos todos;

  // On a server, a job that must see every row.
  Future<int> removeDone() =>
      credentials.asServiceRole(() => todos.deleteByDone(true));
}

Outside asServiceRole the same repository call is made as the current user, or as nobody.

The rule

The first that applies:

# When apikey Bearer token caller
1 inside asServiceRole the service role key the service role key service
2 a client application with a signed-in user (the LoginSession bean, which is SupabaseAuth) the anon key the user's access token, refreshed before it expires user:<id>
3 a server handling a request whose bearer token is a user's token of this project the anon key that token user:<id>
4 otherwise the anon key the anon key anon

For rule 3 the token is passed on when its iss is the project's issuer (spring.supabase.auth.issuer, else <url>/auth/v1), its role is authenticated and it has a sub. A token of another issuer (Keycloak, a test user) is never sent to Supabase: such a request calls as anon.

SupabaseCredentials does not check a token. On a server the resource server has refused anything invalid before a controller runs (see Security on a server); here it is only decided whether to pass the token on.

A key or a token is only ever sent to spring.supabase.url, and no call follows a redirect.

asServiceRole

await credentials.asServiceRole(() async {
  await todos.deleteByDone(true);        // as the service role
  await storage.delete('avatars', path); // this too
});

StorageTemplate.asServiceRole() and SupabaseAuthAdmin use it by themselves.

The interface

Member Meaning
String get apiKey The key sent as apikey.
Future<String> accessToken() The bearer token of the next call.
SupabaseCaller get caller Who the next call is made as: role (SupabaseRole.anon, user, service), id (the user's id) and key (anon, user:<id>, service), which is what a cache key carries.
Future<T> asServiceRole<T>(FutureOr<T> Function() body) Runs body as the service role.

The default is DefaultSupabaseCredentials. A bean of your own of type SupabaseCredentials replaces it.

Keys in a client application

Nothing is forbidden in a Flutter app; it is warned about. A key or a password that ships in an app is the developer's choice (an internal tool, an admin app). At startup, in a Flutter app, each of these that is set is logged once as a warning:

Property What whoever has the app can do
spring.supabase.service-role-key read and write every table past row-level security
spring.supabase.db.url they have the database password
spring.supabase.auth.jwt-secret sign a token for any user (and a client application does not use it: only a server checks tokens)
spring.supabase.service-role-key ships in this application: whoever has the app reads and writes every table past row-level security

The logger is spring.supabase. The anon key is meant to be public. The warning is at startup only: the build's log does not have it.

In Spring (Java)

No counterpart: Spring has no Supabase support. The nearest idea is Spring Security's SecurityContextHolder together with OAuth2AuthorizedClientManager, which gives a call the current user's token.

See also