Katerina Skroumpelou 89e291adec docs: prefer publishable/secret key naming in SDK specs (#45372) ...

## Description

Replaces legacy `anon` / `service_role` key references with the new
`publishable` / `secret` naming across SDK spec files under
`apps/docs/spec/`. Mirrors the rename table established by
[supabase-js#2280](https://github.com/supabase/supabase-js/pull/2280),
so the auto-generated reference docs at
supabase.com/docs/reference/{js,dart,kotlin,python,swift} stay
consistent with the SDK source.

## Files changed

| File | Highlights |
| --- | --- |
| `supabase_js_v2.yml` | Rename example vars `anon_key` →
`publishable_key`, `service_role_key` → `secret_key`; admin notes use
`secret`. |
| `supabase_dart_v2.yml` | Rename `anonKey` param → `publishableKey`
(matches the live Flutter SDK — see
[supabase-flutter/supabase.dart#L81](https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_flutter/lib/src/supabase.dart#L81));
update call-site; example var `serviceRoleKey` → `secretKey`; admin
notes use `secret`. |
| `supabase_kt_v2.yml`, `supabase_kt_v3.yml` | Replace
`'publishable-or-anon-key'` placeholders with `'your-publishable-key'`;
admin notes use `secret`; fix `importAuthToken(\"service_role\")` →
`importAuthToken(\"your-secret-key\")` (the Kotlin SDK's
`importAuthToken(accessToken: String, …)` takes a JWT, not a role name).
|
| `supabase_py_v2.yml` | All `service_role` references → `secret`;
example var `service_role_key` → `secret_key`. |
| `supabase_swift_v2.yml` | Replace placeholders with
`'your-publishable-key'`; admin notes use `secret`; example var
`serviceRoleKey` → `secretKey`. |
| `storage_v0_config.yaml` | Rewrite `ANON_KEY` / `SERVICE_KEY` env var
**descriptions** in publishable/secret terms. **Env var names kept** —
see below. |

## Why the storage env var names are unchanged

`storage_v0_config.yaml` documents the env vars used to configure the
storage server (multi-tenant deployments). The `id` and `title` fields
must match the actual env var names the binary reads. The storage server
still reads its config from env vars literally named `ANON_KEY` and
`SERVICE_KEY`:

-
[`storage/src/config.ts#L614`](https://github.com/supabase/storage/blob/master/src/config.ts#L614)
— `getOptionalConfigFromEnv('SERVICE_KEY')`
-
[`storage/src/config.ts#L625`](https://github.com/supabase/storage/blob/master/src/config.ts#L625)
— `getOptionalConfigFromEnv('ANON_KEY')`

There is no `PUBLISHABLE_KEY` / `SECRET_KEY` reader on master. Renaming
the doc IDs would break self-hosted deployments — users following the
docs would set the wrong env var and the storage server would silently
fall back to generating its own JWT. Until the storage server itself
adds publishable/secret env support, only descriptions can be updated.

(Same reasoning for not bumping `storage_v0_config.yaml` →
`storage_v1_config.yaml`: the `_v0_` tracks the storage server's own API
version, paired with `storage_v0_openapi.json` downloaded from
`supabase.github.io/storage/api.json`. The server hasn't shipped a v1
API.)

## What we deliberately did NOT rename

Per the same rules established in supabase-js#2280:

- **JWT role claims** like `role: 'anon'` / `role: 'service_role'` —
these are functional Postgres role names in JWT payloads, not key
labels.
- **Real SDK identifiers** that haven't been renamed in the source (we
only rename in the doc when the underlying SDK rename has shipped). The
Dart `anonKey` rename was safe to apply because the Flutter SDK already
ships `publishableKey` as the preferred named parameter (with `anonKey`
`@Deprecated`).

## Out of scope

- **All `*_v1.yml` SDK spec files** (`supabase_js_v1`,
`supabase_dart_v1`, `supabase_kt_v1`, `supabase_swift_v1`). Older SDK
versions, not worth churning.
- **`cli_v1_commands.yaml`**. This file is auto-generated by the CLI
repo's release workflow
([`cli/tools/bumpdoc/main.go`](https://github.com/supabase/cli/blob/develop/tools/bumpdoc/main.go))
and the example outputs come from
[`cli/docs/templates/examples.yaml`](https://github.com/supabase/cli/blob/develop/docs/templates/examples.yaml)
— embedded in the CLI binary at build time. Any edits we make here would
be clobbered by the next CLI release. The fix needs to land upstream in
the CLI repo (note: the CLI itself already ships publishable/secret
naming in \`supabase status\` output — see
[`cli/internal/status/status.go#L40-L44`](https://github.com/supabase/cli/blob/develop/internal/status/status.go#L40-L44)
— but the doc-generation template is stale).
- **`supabase_csharp_v0.yml` / `supabase_csharp_v1.yml`** — checked,
already neutral. Both files use a generic `SUPABASE_KEY` env var with no
`anon` / `service_role` references.
- **Renaming the legacy Dart `anonKey` parameter itself** — that's an
SDK-side change. The Flutter SDK already exposes `publishableKey` as the
preferred parameter; full removal of `anonKey` will happen in a future
major version per the SDK's own deprecation comment.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Standardized API key naming across SDK docs: use publishable (client)
and secret (server/admin) key terminology
* Updated server-side admin examples and warnings to require secret keys
and emphasize never exposing them in client code
* Unified initialization examples across JavaScript, Dart, Kotlin,
Python, and Swift
* Corrected Storage spec metadata to point to the proper configuration
file
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

2026-05-04 09:36:05 +03:00

229 KiB

Raw Permalink Blame History

View Raw