## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## Problem
The Docs E2E link checker found broken links throughout docs, starting
with `phone-login.mdx` pointing to `/docs/guides/cli/config` (404).
Old links like `/docs/guides/cli/config` still work on the live site
because `supabase.com` has redirects set up for them, but these links
break on the docs preview site, which is what the E2E check tests
against. These issues look clean on the live site, and I didn't catch
them in my first pass because I was testing production instead of the
preview.
The E2E check only tests the ~20 pages a given PR happens to touch, so
fixing the pages it flagged kept exposing more of the same problem one
page at a time as each fix pulled in a new file. To stop chasing this
incrementally, I cross-referenced every `/docs/guides/*` and
`/docs/reference/*` redirect source in `apps/www/lib/redirects.js`
against actual usage across all of `apps/docs`, and verified each
candidate against the live preview.
## Solution
Rather than updating the Docs E2E link checker, this PR resolves the
links. **Why:** we own these docs, so keeping the links clean without
redirects is keeping the house maintained. See [Broken Window
Theory](https://blog.codinghorror.com/the-broken-window-theory/).
Updated every link still using an old path to point straight at the
current page instead of relying on a redirect. This covers old links
like:
- `/docs/guides/cli/config` →
`/docs/guides/local-development/cli/config`
- `/docs/guides/cli/getting-started` →
`/docs/guides/local-development/cli/getting-started`
- `/docs/guides/cli/local-development` →
`/docs/guides/local-development/database-migrations`
- `/docs/guides/cli/managing-environments` →
`/docs/guides/deployment/managing-environments`
- `/docs/guides/cli/seeding-your-database` →
`/docs/guides/local-development/seeding-your-database`
- bare `/docs/guides/cli` → `/docs/guides/local-development`
- `/docs/guides/platform/compute-add-ons` →
`/docs/guides/platform/compute-and-disk`
- `/docs/guides/platform/shared-responsibility-model` →
`/docs/guides/deployment/shared-responsibility-model`
- `/docs/guides/database` → `/docs/guides/database/overview`
- `/docs/reference/javascript`, `/docs/reference/dart`,
`/docs/reference/kotlin`, `/docs/reference/python`,
`/docs/reference/csharp` → their `/introduction` pages (the redirect's
own destination, `/start`, turned out to be dead even on production — a
separate bug in `redirects.js` I didn't touch here)
- and about 35 more of the same pattern, listed in the commit messages
Also fixed a handful of dead heading anchors found along the way (links
that resolve to the right page but point at a `#section` that got
renamed or moved), including the original `#bigquery` anchor and a few
in `connecting-to-postgres.mdx` where content moved to its own dedicated
page.
Left alone on purpose:
- `content/guides/cli.mdx` — this page has no route in the docs app at
all (no `app/guides/cli/` directory), so it 404s even in production
before the `www` redirect ever fires. Fixing its internal link wouldn't
change that; it needs an actual routing/content decision, not a link
fix.
- A few candidates that already resolve fine as-is (`pg_partman`, bare
`/docs/reference/api`, bare `/docs/reference/cli`) — confirmed via curl,
left untouched.
## Manual testing
1. Confirmed every new link target actually exists by checking the
destination file/page and matching heading anchors.
2. Cross-referenced every `/docs/guides/*` and `/docs/reference/*`
redirect source in `apps/www/lib/redirects.js` against real usage in
`apps/docs`, and curl-verified each old path (404) and new path (200)
against the live PR preview before fixing it.
3. Ran the Docs E2E link checker locally against changed pages.
4. Spot-checked the original broken link from CI
(`/docs/guides/cli/config`) to confirm it now points to a working page.
## I have read the CONTRIBUTING.md file.
YES
## What kind of change does this PR introduce?
Bug fix.
## What is the current behavior?
`api_v2_openapi.json` has a circular reference (`APIErrorObject.issues`
→ `APIErrorObject`), which Redocly can't flatten with `--dereferenced`
("Detected circular reference which can't be converted to JSON"). This
breaks the [weekly docs update
workflow](https://github.com/supabase/supabase/actions/runs/29709444085/job/88251269807).
## What is the new behavior?
- Drop `--dereferenced` from `dereference.api.v1` (both v1 and v2, for
consistency)
- Add a `resolveRefs` helper in `Reference.script.ts` that manually
inlines `$refs`, leaving cycles as an unresolved `$ref` instead of
expanding infinitely
- This also fix the mgmt api update workflow so manual dispatch runs
against the selected branch, by changing checkout `ref` from hardcoded
`master` to `${{ github.ref }}`.
## Additional context
Also fixes `pnpm exec redocly` → `npx --package=@redocly/cli redocly` in
the same Makefile, an unrelated pnpm 11 recursive-exec bug hit while
debugging this workflow.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Updated API specification bundling and linting commands to use the
current Redocly CLI invocation style.
* Improved documentation processing behavior for dereferenced specs,
including guidance around circular references.
* Preserved existing generated specification outputs and validation
settings.
* **Chores**
* Updated the Mgmt API docs automation workflow formatting (YAML string
quoting and schedule/input values).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What
Updates the Dart/Flutter reference
(`apps/docs/spec/supabase_dart_v2.yml`) for features shipped in
[`supabase/supabase-flutter`](https://github.com/supabase/supabase-flutter)
in July (through the July 17 storage CDN-cache additions).
Built on the **new reference pipeline** (#47224 / #47994): each method's
section is inherited from the nearest section-header entry in the YAML,
and subcategory overviews are committed partials under
`spec/reference/dart/v2/partials/`. `common-client-libs-sections.json`
is **not** touched.
Scoped to items **not** already covered by #47728 (OAuth server
authorization details, custom providers admin, `explain` format,
realtime `onHeartbeat` and filter examples). Rebased onto `master` now
that #47994 and #47728 have landed.
## New reference entries
**Storage**
- Vector buckets (new **Vector Buckets** section):
create/get/list/delete bucket, index create/get/list/delete/access, and
vector put/get/list/query/delete (`supabase.storage.vectors`)
- Analytics (Iceberg) buckets (new **Analytics Buckets** section):
`createAnalyticsBucket`, `listAnalyticsBuckets`,
`deleteAnalyticsBucket`, and the `analyticsCatalog()` accessor
- `listPaginated` (list files v2), under File Buckets
- `downloadStream()` (streaming file downloads), under File Buckets
- `purgeCache()` (object CDN cache invalidation) and
`purgeBucketCache()` (bucket CDN cache invalidation)
**Auth**
- `signInWithWeb3`
- OAuth server `listGrants` and `revokeGrant` (in the **OAuth Server**
section, `supabase.auth.oauth`)
**Database**
- `stripNulls()` modifier
## Enrichments to existing entries
- Storage: `cacheNonce` on `getPublicUrl` / `createSignedUrl` /
`download`; filter/sort/pagination options on `listBuckets`
- Auth: `channel` on `mfa.challenge()`; `currentPassword` on
`updateUser`; async `getSession()` note and example; `friendlyName` on
`registerPasskey()` and `passkey.startRegistration()`
- Functions: `abortSignal` on `invoke`
## Pipeline plumbing
- New partials: `analytics-buckets.json`, `vector-buckets.json`,
`oauth-server.json`
- `generate-dart-reference.ts`: registers `analytics-buckets`,
`vector-buckets`, and `oauth-server-api` group-header ids in
`HEADER_IDS` so they render as section overviews rather than methods
## Source PRs
supabase-flutter: #1547, #1554, #1557, #1559, #1561, #1563, #1578,
#1579, #1580, #1585, #1588, #1590, #1591, #1593, #1603, #1607, #1608
## Verification
`pnpm codegen:references:dart` builds cleanly: the generator writes 141
method declarations (all ids resolve to a section, no invalid method
names, no slug collisions), and the nav renders the Analytics Buckets,
Vector Buckets, and OAuth Server sections with the expected methods.
## Notes
- Skipped (no reference home / would need product decisions): Iceberg
namespace/table management (the full `IcebergRestCatalog` API, which
lives in a standalone `iceberg-js` package upstream), `dryRun`,
functions exception subtypes, trace-context headers, `persistSession`,
configurable postgrest timeout/retry.
- `storageanalytics-from` maps to Dart's `analyticsCatalog(bucketId)`
(the Iceberg catalog entry point), since Dart has no `analytics.from()`
equivalent.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Expanded Dart docs with Web3 sign-in plus passkey, MFA channel, and
OAuth grant listing/revocation.
* Added storage APIs/examples for listing buckets with options, CDN
cache bypass via `cacheNonce`, and cache/purge support.
* Documented `stripNulls()` database modifier and cursor-based paginated
storage listing.
* **Documentation**
* Updated auth references with optional `currentPassword`,
`friendlyName`, and clarified `currentSession` vs `getSession()`.
* Added `abortSignal` support and examples for
`supabase.functions.invoke()`.
* **Bug Fixes**
* Improved Dart reference generation so analytics/vector bucket sections
aren’t emitted as method declarations.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
> **Stacked on #47994** (`docs/dart-reference-categories-in-yaml`).
Review/merge that first; GitHub will retarget this to `master` once it
lands.
## What
Adds Dart client library reference entries
(`apps/docs/spec/supabase_dart_v2.yml`) for features shipped in
[`supabase/supabase-flutter`](https://github.com/supabase/supabase-flutter)
(parity with `supabase-js`).
Rebuilt on the **new reference pipeline** (#47224 / #47994): each
method's section comes from `category` / `subcategory` fields on its own
YAML entry, with subcategory overviews as committed partials under
`spec/reference/dart/v2/partials/`. As a result this PR no longer
touches `common-client-libs-sections.json` or `supabase_js_v2.yml` (the
earlier shared-nav id rename is unnecessary now that Dart no longer
reads that file).
## Changes
**Auth (OAuth 2.1 server)** — new **OAuth Server** section
- `oauth.getAuthorizationDetails()`, `oauth.approveAuthorization()`,
`oauth.denyAuthorization()`
**Auth admin** — new **Custom Provider Admin** section
-
`admin.customProviders.listProviders/createProvider/getProvider/updateProvider/deleteProvider`,
including `customClaimsAllowlist`
**Realtime**
- `onHeartbeat`
- `onPostgresChanges` examples for the new pattern/negated filter
operators, multiple filters, and column selection
**Postgrest**
- `explain()` `format` option (`ExplainFormat.text` / `.json`)
## Pipeline plumbing
- New partials: `oauth-server.json`, `custom-provider-admin.json`
- `generate-dart-reference.ts`: registers `oauth-server-api` and
`admin-custom-providers-api` group-header ids in `HEADER_IDS`
## Source PRs
supabase-flutter: #1499, #1516, #1517, #1519, #1526
## Verification
`pnpm codegen:references:new` builds cleanly and the nav renders the new
**OAuth Server**, **Custom Provider Admin**, and Realtime
**onHeartbeat** entries.
## Notes
- `RealtimeChannelConfig.replicationReady` (#1526) is omitted since
there is no reference slot for channel-config options.
- The **OAuth Server** section also appears in #47971 (which adds
`listGrants` / `revokeGrant`). Whichever lands second should drop the
duplicate section header/partial and keep both sets of methods.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added OAuth 2.1 server consent-flow methods for retrieving, approving,
and denying authorization requests.
* Added admin APIs for managing custom OIDC/OAuth providers.
* Added Realtime heartbeat monitoring and advanced Postgres change
filters.
* Added text and JSON output options for query explanations.
* **Documentation**
* Expanded Dart API reference coverage across Auth, MFA, Passkeys,
Database, Realtime, and Storage.
* Added dedicated reference sections for OAuth Server and Custom
Provider administration.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What
Addresses @jeremenichelli's feedback that the Dart v2 reference required
maintaining section metadata separately from the spec. The reference now
derives every method's section from the spec YAML itself, with **no
per-method metadata**.
## How
Each **section-header** entry in `supabase_dart_v2.yml` carries the
`category` and optional `subcategory` that every method after it
inherits, up to the next header:
- Existing subcategory headers gain a `category`/`subcategory`:
`auth-mfa-api`, `passkey-api`, `admin-api`, `admin-passkey-api`,
`file-buckets`, `using-modifiers`, `using-filters`.
- New top-level category headers mark the sections that previously had
no header: `auth-api`, `functions-api`, `database-api`, `realtime-api`.
`generate-dart-reference.ts` walks the spec in order, tracking the
current section from the most recent header, and tags each method's
declaration with it. A method may still set `category`/`subcategory`
explicitly to override, and the converter errors if a method appears
before any header.
## Why this is less work
- **Authoring a new method:** place it in the right section. No
`category`/`subcategory` fields, no nav file edit.
- **Adding a section:** one header entry (with `category`/`subcategory`)
plus its overview partial.
- `common-client-libs-sections.json` is not touched (it still drives the
legacy-pipeline SDKs).
## Verification
The generated navigation (`content/reference/dart/v2/sections.json`,
`bySlug.json`) is **byte-for-byte identical** to the previous output.
`pnpm codegen:references:new` writes 105 method declarations across 5
categories with no orphaned methods and no slug collisions.
Supersedes the earlier per-method-`category` approach on this branch.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Improved Dart/Flutter API reference organization by leveraging
spec-provided `category` and `subcategory` taxonomy for clearer grouping
(Auth, Passkey, Edge Functions, Database, Realtime, Storage, and
database modifiers/filters).
* Updated reference generation to use structured in-spec section
headers, resulting in more consistent published categorization and
navigation.
* **Bug Fixes**
* Enhanced validation and error messaging for entries that can’t be
assigned to a section/category, including clearer guidance on how to fix
incomplete spec items.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Adds a docs guide, "Choosing a server-side package", that explains when
to use `supabase-js`, `@supabase/ssr`, or `@supabase/server` when
working with Supabase from JavaScript on the server. It includes a
decision table and a short code example for each, with one rule up
front: cookie-based sessions in SSR frameworks use `@supabase/ssr`,
per-request header auth in Edge Functions and other backend runtimes
uses `@supabase/server`, and `supabase-js` is the base client both wrap.
The guide is surfaced from the Auth overview page and the sidebar, and
is cross-linked from the `supabase-js` and `@supabase/server` reference
introductions so it is reachable from where developers start. It also
states that the packages coexist and are not replacements for each
other, and keeps combining `@supabase/server` with `@supabase/ssr` as an
advanced section.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Added a guide explaining how to choose between Supabase server-side
JavaScript packages.
- Added the guide to Auth navigation and the getting-started content
listings.
- Added links to the new guidance throughout relevant JavaScript and
server documentation.
- **Documentation**
- Clarified when to use cookie-based sessions versus header-based
authentication.
- Added package comparisons, usage examples, advanced guidance, and
related next steps.
- Updated spelling support for framework names used in the
documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## Summary
Updates reference specs based on new stable releases in two SDK repos
(JS spec is auto-generated and was excluded).
## Changes analyzed
| SDK | Repo | Stable tag range |
|-----|------|-----------------|
| dart | supabase/supabase-flutter |
`supabase_flutter-v2.15.0...supabase_flutter-v2.15.4` |
| swift | supabase/supabase-swift | `v2.48.0...v2.49.0` |
## Documentation updates
### Dart (supabase_flutter-v2.15.0 → v2.15.4)
- **`supabase_dart_v2.yml`**: Updated `deleteUser()` — added
`shouldSoftDelete: bool` parameter with example
- **`supabase_dart_v2.yml`**: Updated `from.createSignedUrl()` — added
`download: DownloadBehavior?` parameter with example
- **`supabase_dart_v2.yml`**: Updated `from.getPublicUrl()` — added
`download: DownloadBehavior?` parameter with example
- **`supabase_dart_v2.yml`**: Added new `from-create-signed-upload-url`
entry with `upsert: bool` parameter (was missing from the Dart spec)
### Swift (v2.48.0 → v2.49.0)
- **`supabase_swift_v2.yml`**: Updated `explain()` — added note on
`ExplainFormat` enum (`.text`/`.json`), added JSON format example
- **`supabase_swift_v2.yml`**: Updated `createBucket()` and
`updateBucket()` examples — `BucketOptions(public:)` renamed to
`BucketOptions(isPublic:)`
- **`supabase_swift_v2.yml`**: Updated `createSignedURL()` and
`getPublicURL()` download examples — `download: Bool` replaced by
`download: DownloadBehavior?` (`.withOriginalName` / `.named()`)
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added guidance for soft-deleting users, including a new example.
* Documented download behavior for signed URLs and public URLs,
including original or custom filenames.
* Added documentation and examples for generating signed upload URLs,
with optional overwrite support.
* Expanded query plan documentation to show JSON output.
* Updated storage examples to match the latest option names and
recommended usage.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: Claude <noreply@anthropic.com>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
Docs update.
*
https://docs-git-docs-wire-server-v1-reference-supabase.vercel.app/docs/reference/server/introduction
*
<img width="417" height="628" alt="Screenshot 2026-07-06 at 6 13 33 PM"
src="https://github.com/user-attachments/assets/9fc27b04-038b-4434-8855-94051f898b5d"
/>
## What is the current behavior?
`@supabase/server` has no reference documentation page in the Supabase
docs. The library publishes a TypeDoc spec to GitHub Pages but the docs
pipeline was not wired up to consume it.
## What is the new behavior?
- Adds `spec/reference/server/v1/` with a `config.json` (category order:
Middleware, Primitives, Adapters, Errors, Types) and `partials/` for the
introduction and installing pages.
- Adds a `download.server.v1` Makefile target that fetches
`https://supabase.github.io/server/spec.json` into
`spec/reference/server/v1/server.json`, and wires it into the top-level
`download` target so it runs with the rest.
- Registers `server-v1` in `SUPPORTS_NEW_REFERENCE_PROCESS` so the build
pipeline picks up the new spec directory and generates
`content/reference/server/v1/` at build time.
- Seeds the generated `docs/ref/server/` partials (introduction and
installing) that the reference router serves.
## Additional context
The TypeDoc spec is produced by `@supabase/server`'s `docs.yml` workflow
on every push to `main`, so `make download.server.v1` will always pull
the latest published API surface. The companion PR in the server repo
([supabase/server#95](https://github.com/supabase/server/pull/95)) adds
the `@category` tags that the pipeline requires for symbols to appear in
navigation.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added a new **Server SDK** item under **Reference**, linking to
`/reference/server` and marked with a **New** badge.
* Published **Server Reference v1** documentation for
`@supabase/server`, including **Introduction** and **Installing** pages.
* **Chores / Improvements**
* Enhanced the reference documentation generation to include Server v1
content.
* Improved reference detail handling (including clearer TypeDoc output
such as **Deprecated** notes).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
## What
Routes the **Dart/Flutter v2** reference through the new
reference-content pipeline (`scripts/build-reference-content.ts` +
`spec/reference/dart/v2/`), the same one JavaScript v2 already uses.
Dart v1 stays on the legacy YAML pipeline.
## How
Dart has no upstream TypeDoc dump, so this follows the reference
README's "adapt other formats as a pre-step" approach:
- **`scripts/generate-dart-reference.ts`** converts the committed legacy
spec (`spec/supabase_dart_v2.yml`) plus the shared section tree into a
TypeDoc-shaped dump at `spec/reference/dart/v2/supabase_flutter.json`
(gitignored, like every other dump). Each Dart method becomes a
`variant: 'declaration'` node tagged with `@category`/`@subcategory` and
carries the legacy function shape (description, notes, params, examples)
on a non-TypeDoc `content` field.
- **`build-reference-content.ts`** gains a small, backward-compatible
addition: it spreads a declaration's `content` straight onto the
`functions.json` entry. The renderer then shows params/examples/notes
exactly as the legacy YAML did, with no typeSpec round-trip. The field
is absent for real TypeDoc dumps, so **JavaScript output is unchanged**
(existing JS snapshot still passes).
- `dart-v2` added to `SUPPORTS_NEW_REFERENCE_PROCESS`; the v2 `specFile`
is dropped from the nav entry so the legacy generator skips it.
- Dart search ingest switched to the new-pipeline loader.
- `config.json` + hand-authored partials (intro markdown,
`initializing`, and subcategory overviews like `using-filters`,
`auth-mfa`) added under `spec/reference/dart/v2/partials/`, mirroring
the JS lib.
- The dart dump is regenerated in `codegen:references:new` and in CI; a
self-contained `dart/v2` snapshot test covers the full YAML → dump →
content path.
## Verification
- `vitest run scripts/build-reference-content.test.ts` — both JS and
Dart snapshots pass.
- 112 function sections all resolve to renderable `functions.json`
entries (104 methods + 7 subcategory overviews + `initializing`).
- `tsc --noEmit` clean for all changed files.
- Legacy generator confirmed to skip dart v2 (only `dart.v1.*`
regenerated).
> Note: the live dev server (which needs the Supabase backend) was not
run; verification was done at the data-pipeline level plus parity with
the production JS pipeline behavior.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added Dart v2 reference documentation sections, including Installing,
Initializing, Filters, Modifiers, Auth Admin, MFA, Passkeys, File
Buckets, Introduction, and Upgrade guidance.
* Expanded the Dart v2 reference pipeline so Dart API pages are
generated from the newer reference content flow.
* **Bug Fixes**
* Improved Dart reference rendering by preserving legacy descriptions,
notes, params, and examples in generated function entries.
* Updated Dart v2 reference search to use the new pipeline’s generated
content so results and navigation stay in sync.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
## Summary
Updates the Dart (`supabase_flutter`) passkey documentation to reflect
[supabase-flutter#1444](https://github.com/supabase/supabase-flutter/pull/1444),
which changed `registerPasskey()` and `signInWithPasskey()` to accept a
`PasskeyAuthenticatorInterface` parameter instead of bundling the
`passkeys` plugin directly.
## Changes
- `apps/docs/content/guides/auth/passkeys.mdx` — updated the Dart tab
under "Enable in the client" to show how to construct an authenticator
(e.g. `PasskeyAuthenticator` from the `passkeys` package), and updated
the `registerPasskey()` / `signInWithPasskey()` code samples to pass it.
- `apps/docs/spec/supabase_dart_v2.yml` — added the new `authenticator`
parameter to the `signInWithPasskey()` and `registerPasskey()` reference
entries and updated their examples/notes.
## Test plan
- [ ] Review rendered guide and reference pages for the Dart tab of the
passkeys docs
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated Dart passkey authentication guides to reflect the latest usage
pattern.
* Passkey sign-in and registration now show a required authenticator
being passed in.
* Added clearer setup examples using a passkey authenticator
implementation.
* Clarified that the app must provide the authenticator when using
passkey flows.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
Updates docs based on stable releases in `supabase/supabase-swift`.
## Changes analyzed
- **SDK**: swift
- **Repo**: https://github.com/supabase/supabase-swift
- **Stable tag range**: `v2.47.2...v2.48.0`
- **Commits**:
`716e0de6e7e0ec8eba54c6c4dfb8e980b3d51370...e5020ae5a1d01c46cc60fb5eb01157666d7214b6`
## Documentation updates
### `apps/docs/spec/supabase_swift_v2.yml`
- Added `sign-in-with-passkey` entry —
`signInWithPasskey(presentationAnchor:)` high-level helper (iOS
16+/macOS 13+, experimental)
- Added `register-passkey` entry —
`registerPasskey(presentationAnchor:)` high-level helper (iOS 16+/macOS
13+, experimental)
- Added `passkey-api` group stub with 7 lower-level method entries:
- `passkey-list` — `listPasskeys()`
- `passkey-update` — `renamePasskey(id:friendlyName:)`
- `passkey-delete` — `deletePasskey(id:)`
- `passkey-start-registration` — `getPasskeyRegistrationOptions()`
- `passkey-verify-registration` —
`verifyPasskeyRegistration(challengeId:credentialResponse:)`
- `passkey-start-authentication` — `getPasskeyAuthenticationOptions()`
- `passkey-verify-authentication` —
`verifyPasskeyAuthentication(challengeId:credentialResponse:)`
- Updated `auth-mfa-api` overview notes to mention WebAuthn MFA
(experimental)
- Updated `mfa-enroll` notes and added `enrollWebAuthnFactor` example
- Updated `mfa-verify` notes and added `verifyWebAuthnFactor` example
### `apps/docs/content/guides/auth/passkeys.mdx`
- Added Swift tabs to: Enable in the client, Register a passkey, Sign in
with a passkey, Two-step API, Manage passkeys
- Updated SDK version note to include `supabase-swift` v2.48.0
- Updated reference links to include Swift
All new Swift passkey APIs are gated behind `@_spi(Experimental) import
Supabase`.
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Documentation
* Expanded Swift SDK passkeys documentation to cover enabling,
registering, signing in, managing, and Admin-related notes.
* Added experimental Swift guidance for WebAuthn/passkeys, including
updated minimum SDK version requirements.
* Extended MFA to support WebAuthn/passkeys enrollment and verification
(in addition to existing methods).
* Added reference documentation for low-level passkey APIs to support
custom authentication flows.
## Chores
* Updated documentation linting spell-check allow list to include
**visionOS**.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
Updates docs based on stable releases in `supabase/supabase-flutter`.
## Changes analyzed
- **SDK**: dart
- **Repo**: https://github.com/supabase/supabase-flutter
- **Stable tag range**:
`supabase_flutter-v2.14.1...supabase_flutter-v2.15.0`
- **Commits**:
`81c1590728a5e08bebdc152bd59a7c1e7644c8b2...9030650b74e253020f8c614b3bfb2c993b6061af`
## Documentation updates
`apps/docs/spec/supabase_dart_v2.yml` — adds entries for the new passkey
APIs landed in `supabase_flutter-v2.15.0`
([gotrue#1392](https://github.com/supabase/supabase-flutter/pull/1392),
[supabase_flutter#1408](https://github.com/supabase/supabase-flutter/pull/1408)):
- `signInWithPasskey()` / `registerPasskey()` — high-level helpers on
`supabase_flutter` that drive the full WebAuthn ceremony.
- `auth.passkey.*` — server side of the WebAuthn ceremony: `list`,
`update`, `delete`, `startRegistration`, `verifyRegistration`,
`startAuthentication`, `verifyAuthentication`.
- `auth.admin.passkey.*` — admin endpoints: `listPasskeys`,
`deletePasskey`.
`apps/docs/content/guides/auth/passkeys.mdx` — adds Dart code examples
to every passkey section (Enable in the client, Register, Sign in,
Two-step API, Manage, Admin API) and points the reference links at both
the JavaScript and Dart specs. Bumps the "Requires" admonition to
include `supabase_flutter v2.15.0`.
Other v2.14.2 / v2.15.0 changes that did not require doc updates:
- `feat(realtime): protocol format 2.0.0` — protocol versions are
already documented in `realtime/protocol.mdx`; the SDK now defaults to
v2.0.0 but exposes a `version: RealtimeProtocolVersion.v1` opt-out,
which is an SDK detail rather than a docs change.
- `fix(gotrue): support asymmetric JWTs in getClaims` — bug fix to the
existing `auth.getClaims` (no new API).
- The rest are bug fixes and internal refactors (storage
`createSignedUrls` null handling, postgrest stack traces, gotrue
refresh-token races, PKCE email-change, realtime deaf-socket guards,
lint/test/CI hygiene).
`common-client-libs-sections.json` already contains entries for every
new spec `id`, so the sidebar nav picks them up automatically.
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added Dart language examples to passkey authentication guide covering
client initialization, user registration, sign-in workflows, two-step
ceremony flows, and passkey management operations
* Updated Dart client specification to document new passkey
authentication functions and admin-level passkey management capabilities
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
Include the v2 mgmt API spec in the official docs. This PR merges the v1
and v2 specs when generating the reference, with v2 taking precedence on
conflicts.
Fixes API-1215
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Docs now include API v2 reference: log-drain management
(list/create/update/delete) and project transfer (preview/transfer).
* **Documentation**
* Generated API reference now merges v1 and v2 specs so both appear in
the docs and section listings.
* New v2 operations added to Analytics and Projects documentation
sections.
* **Chores**
* Docs generation pipeline updated to accept and process multiple API
spec inputs.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
# Second try of making a new better process for SDK automation
Instead of building a new pipeline. We will take the lessons learned
form round 1, plus the good design and improvement on DX quality for
drop-in file as a single step required from SDK team and produce almost
identical set of files as used right now to render using the current
pipeline.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* New reference-content pipeline producing per-library reference
artifacts and integrating into prebuilds, search ingestion, and
rendering (type-aware examples).
* **Documentation**
* Added comprehensive JavaScript SDK v2 reference content and partials
(Auth MFA, passkeys, admin, TypeScript support, filters, modifiers,
Installing, Initializing, Buckets, etc.).
* **Tests & CI**
* Added regression snapshot test and updated workflows to refresh
reference snapshots and ensure spec downloads.
* **Chores**
* Updated ignore rules, build scripts, Makefile targets, and package
lifecycle hooks.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Katerina Skroumpelou <mandarini@users.noreply.github.com>
Co-authored-by: Katerina Skroumpelou <sk.katherine@gmail.com>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
Docs update.
## What is the current behavior?
No docs for client-side trace propagation with the JS SDK. Users with
OpenTelemetry-instrumented apps had no way to find out that supabase-js
can attach W3C Trace Context headers and that `trace_id` shows up in API
Gateway and Edge Function logs.
## What is the new behavior?
New guide at `/guides/telemetry/client-side-tracing` covering
requirements, opt-in setup (`tracePropagation: true`), advanced options,
domain scoping, where `trace_id` appears in Supabase logs, and
troubleshooting. Linked from the Logging & observability nav.
Preview:
https://docs-git-docs-otel-sdk-supabase.vercel.app/docs/guides/telemetry/client-side-tracing
## Additional context
First of several planned SDK tracing guides. When the next SDK gets one
we'll restructure into a shared `tracing/` folder.
## Summary by CodeRabbit
* **Documentation**
* New comprehensive guide for client-side trace propagation with the JS
SDK: explains W3C Trace Context header behavior, requirements, setup
steps, opt-in examples, advanced configuration, domain/security notes,
and troubleshooting when trace IDs are missing.
* Added a new "Tracing with the JS SDK" entry in the Logging &
observability navigation for easy access to the guide.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* New comprehensive guide for client-side trace propagation with the JS
SDK: explains W3C Trace Context header behavior, requirements, setup
steps, opt-in examples, advanced configuration, domain/security notes,
and troubleshooting when trace IDs are missing.
* Added a "Tracing with the JS SDK" entry under Logging & observability
for quick access.
* Documentation metadata updated to reference the latest source
snapshots.
* Lint rules updated to allow "OpenTelemetry", "Zipkin", and "noop".
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/46218?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Summary
Updates reference docs based on recent **stable** releases across
supabase-js, supabase-flutter, and supabase-py. Only changes that landed
in a stable tag are documented.
## Changes analyzed
| SDK | Repo | Stable tag range | Notes |
|-----|------|-----------------|-------|
| js | supabase/supabase-js | `v2.105.0` → `v2.105.3` | Bug fixes and
type improvements; no doc-worthy API changes |
| dart | supabase/supabase-flutter | → `supabase_flutter-v2.13.0` |
`anonKey` deprecated → `publishableKey` |
| py | supabase/supabase-py | `v2.29.0` → `v2.30.0` | New: `.select()`
chaining on write builders |
| swift | supabase/supabase-swift | `v2.46.0` | Dependency bumps only |
| kt | supabase-community/supabase-kt | `3.6.0` | Test coverage
improvements only |
| csharp | supabase-community/supabase-csharp | `v1.1.2` | No changes |
> **Note**: The JS `storage.from().exists()` breaking behavior change
and `PostgrestError instanceof` fix were intentionally excluded — they
are only in the `v3.0.0-next` pre-release branch, not in any stable
`v2.x` tag.
## Documentation updates
### `apps/docs/spec/supabase_dart_v2.yml`
- Rename `anonKey` parameter → `publishableKey` in
`Supabase.initialize()` to match the deprecation in
[supabase-flutter#1360](https://github.com/supabase/supabase-flutter/pull/1360)
(landed in `supabase_flutter-v2.13.0`)
- Update Flutter example to use `publishableKey:` named argument
- Note that `anonKey` is still accepted but deprecated
### `apps/docs/spec/supabase_py_v2.yml`
- Add `.select()` chaining examples to `insert()`, `update()`,
`upsert()`, and `delete()` write builders, newly supported in
[supabase-py v2.30.0](https://github.com/supabase/supabase-py/pull/1383)
- Add notes to each write method mentioning select chaining capability
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Release Notes
* **Documentation**
* Dart SDK: Updated client initialization to use `publishableKey`
parameter; deprecated `anonKey` remains supported for backward
compatibility.
* Python SDK: Added examples demonstrating how to chain `.select()` with
write operations (`insert()`, `update()`, `upsert()`, `delete()`) to
retrieve specific columns from modified rows.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## 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>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
Replaces "stored procedures" with "functions" for everything related to
the Data API.
## Additional context
It's not accurate to call database functions "stored procedures". It may
have been that way before Postgres 11, but now it causes confusion
because PostgREST allows functions and not stored procedures.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Standardized terminology across docs, SDK guides, CLI/config specs,
examples, UI, and config comments to use "database functions" instead of
"stored procedures".
* Updated API docs, CLI/config descriptions, Studio UI labels, help
text, empty-state and navigation copy, RPC documentation, and example
text for consistency.
* Adjusted explanatory text and error/help messages to reflect the
revised terminology.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
- Adds a warning note to `onAuthStateChange()` that an `onError` handler
is **required**
- Updates all three Dart code examples (spotlight, specific-event,
unsubscribe) to include `onError`
## Background
Network errors (e.g. a token refresh attempted while the device is
offline) are emitted as stream errors on `onAuthStateChange`. If no
`onError` handler is provided, Dart rethrows them as unhandled zone
exceptions, crashing the app.
This is tracked in supabase/supabase-flutter#1281. The SDK itself
already handles this internally (`supabase_auth.dart` has its own
`onError`), but user-facing code that calls `.listen()` without
`onError` is still vulnerable.
The companion SDK fix (example app + doc comment in
`gotrue_client.dart`) is in a separate PR in
`supabase/supabase-flutter`.
## Test plan
- [ ] Review the rendered diff in the Dart reference docs
(`/docs/reference/dart/auth-onauthstatechange`)
- [ ] Confirm all three code examples now show `onError`
- [ ] Confirm the new note is visible in the Notes section
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Clarified auth-state change docs to require explicit error handling in
listeners and updated all examples to show an error callback to avoid
unhandled exceptions.
* Updated the documented list of auth event names to the new set
(including initialSession and mfaChallengeVerified) and adjusted
examples accordingly.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
Docs - [CLI Config
Reference](https://supabase.com/docs/guides/local-development/cli/config#auth.mfa.totp.enroll_enabled)
## What is the current behavior?
Default values in the cli config reference for mfa totp are set as
`true` which is not correct.
## What is the new behavior?
Changed to use `false` and match the default `config.toml`.
<img width="868" height="723" alt="Screenshot 2026-04-01 at 15 53 54"
src="https://github.com/user-attachments/assets/5e3e33a0-5edb-44d6-a013-4327aef537b4"
/>
## Additional context
Fixes: https://github.com/supabase/cli/issues/3737
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Updated CLI configuration defaults for TOTP multi-factor
authentication. TOTP enrollment and verification are now disabled by
default. Users relying on these features may need to manually enable
them in their configuration if required.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
Docs update
## What is the new behavior?
- Added docs for analytics and vector buckets
- Added missing docs for some storage bucket methods
- Improved OAuth / OTP guide
- Small fixes
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Documentation
- Updated Kotlin authentication guides with improved examples, API
naming consistency, and comprehensive Kotlin Multiplatform support
- Added documentation for identity linking with ID tokens
- Expanded Storage API documentation with new file operation methods
(`exists()` and `info()`)
- Added extensive vector storage bucket operations and management
documentation
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
