
# 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

```dart
@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`](auth.md)) | 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](security.md)); 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

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

- It holds for the body and for everything the body starts: it is kept in the `Zone`.
- Without `spring.supabase.service-role-key` it throws a `StateError` before the body runs.
- An error of the body comes out as it is.
- The service role passes row-level security: use it for jobs and administration, never for a user's request as a whole.

`StorageTemplate.asServiceRole()` and [`SupabaseAuthAdmin`](auth.md) 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](cache.md) 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) |

```text
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

- [Sign-in in a client application](auth.md)
- [Security on a server](security.md)
- [Caches](cache.md)
- [The security context](../spring-security-core/security-context.md)
