fix(supabase): warn instead of throw for unrecognized sb_ API key subtypes by mandarini · Pull Request #2526 · supabase/supabase-js

mandarini · 2026-07-15T10:21:03Z

Description

Relaxes the API key format check in createClient() so that it never throws. Temporary keys (sb_temp_...) are now recognized and accepted silently, and any other unrecognized sb_ key subtype logs a one-time console.warn instead of failing client construction.

What changed?

packages/core/supabase-js/src/lib/fetch.ts: replaced assertSupportedApiKey() (which threw for any sb_ key other than sb_publishable_... / sb_secret_...) with checkApiKeyFormat():
- sb_temp_... keys are accepted silently.
- Any other unrecognized sb_ subtype logs a one-time console.warn (deduplicated per subtype) suggesting an SDK upgrade, and the client proceeds. The key value is never included in the warning.
- Legacy JWT keys and sb_publishable_... / sb_secret_... keys are unaffected.
packages/core/supabase-js/src/SupabaseClient.ts: constructor call site updated to the new function. An empty key still throws (supabaseKey is required.).
Header behavior from fix(functions): stop sending API key in Authorization header for function calls #2511 is unchanged: new-format keys are still never sent as Authorization: Bearer on Edge Function calls. Temporary and unrecognized sb_ subtypes keep the legacy behavior (apikey header plus Authorization: Bearer fallback), which is what these keys relied on before the validation was introduced.
Tests: rewrote the format-check unit tests (warn instead of throw, silent acceptance of temporary keys, warn deduplication, key value never present in the message) and added header pins proving temporary keys are sent as apikey plus Authorization: Bearer fallback on both the regular and the Edge Functions fetch paths.
docs/MIGRATION.md: removed the "Unrecognized API key formats now throw" section. With the throw gone there is no user action to document; the rest of the "Edge Functions auth headers" section from fix(functions): stop sending API key in Authorization header for function calls #2511 still applies and is untouched.

Why was this change needed?

Versions 2.110.4 and 2.110.5 threw synchronously in the SupabaseClient constructor for any sb_ key that was not sb_publishable_... / sb_secret_... (a future-proofing guard added in #2511). The sb_ key family can grow beyond what any released SDK version knows about, so hard-failing at construction breaks clients that are given valid keys of a newer subtype, such as the temporary sb_temp_... keys. The SDK is not the authority on key validity: with this change, an unrecognized and genuinely invalid key surfaces as an auth error from the server, while an unrecognized but valid key keeps working, with a one-time console warning that an SDK upgrade may be needed.

Screenshots/Examples

Before (2.110.4 and 2.110.5):

createClient(url, 'sb_temp_...')
// throws: "Unrecognized Supabase API key format. ... please upgrade @supabase/supabase-js."

After:

createClient(url, 'sb_temp_...') // works, no warning
createClient(url, 'sb_futuretype_...') // works, one-time console.warn suggesting an SDK upgrade

Breaking changes

None. This removes a constructor throw, so it strictly widens the set of accepted inputs. Keys that worked before continue to work identically.

This PR contains no breaking changes

Checklist

I have read the Contributing Guidelines
My PR title follows the conventional commit format: <type>(<scope>): <description>
I have run pnpm nx format to ensure consistent code formatting
I have added tests for new functionality (if applicable)
I have updated documentation (if applicable)

Additional notes

assertSupportedApiKey was exported from src/lib/fetch.ts but never re-exported from the package entry point, so renaming it to checkApiKeyFormat does not change the public API.
The warning message intentionally does not enumerate the recognized key prefixes, so future key subtypes will not require message updates.
The Supabase dashboard downgraded to @supabase/supabase-js 2.110.1 in Revert "feat: update @supabase/*-js libraries to v2.110.5" (#47918) supabase#47945 to avoid this throw; that pin can be lifted once this fix is in a stable release.

coderabbitai · 2026-07-15T10:21:12Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b347ccdd-b9a1-4064-9d60-ac410d9a1dca

📥 Commits

Reviewing files that changed from the base of the PR and between c44d4a6 and 491cf3a.

📒 Files selected for processing (2)

packages/core/supabase-js/src/lib/fetch.ts
packages/core/supabase-js/test/unit/fetch.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

packages/core/supabase-js/test/unit/fetch.test.ts

📝 Walkthrough

Summary by CodeRabbit

New Features
- Added support for temporary API keys.
- Temporary keys now use both API key and bearer authentication headers.
Bug Fixes
- Unrecognized API key formats no longer prevent client creation.
- The SDK now logs a single warning per unrecognized key subtype and does not expose the raw key value.
- Temporary key authentication continues to work even when bearer fallback is configured to be omitted.
Documentation
- Updated migration guidance related to unrecognized API key format behavior.

Walkthrough

API key validation now uses checkApiKeyFormat, which accepts legacy JWT, recognized sb_, and temporary key formats without throwing. Unknown sb_ subtypes emit a deduplicated warning that excludes the key value. SupabaseClient uses the new helper, and tests cover client creation, warning behavior, temporary-key authentication headers, and omission handling. The migration guide no longer documents exceptions for unrecognized sb_ formats.

Sequence Diagram(s)

sequenceDiagram
  participant SupabaseClient
  participant checkApiKeyFormat
  participant Console
  SupabaseClient->>checkApiKeyFormat: Validate supabaseKey format
  checkApiKeyFormat->>Console: Warn once for unknown sb_ subtype
  checkApiKeyFormat-->>SupabaseClient: Continue without throwing

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

pkg-pr-new · 2026-07-15T10:22:28Z

Open in StackBlitz

@supabase/auth-js

npm i https://pkg.pr.new/@supabase/auth-js@2526

@supabase/functions-js

npm i https://pkg.pr.new/@supabase/functions-js@2526

@supabase/postgrest-js

npm i https://pkg.pr.new/@supabase/postgrest-js@2526

@supabase/realtime-js

npm i https://pkg.pr.new/@supabase/realtime-js@2526

@supabase/storage-js

npm i https://pkg.pr.new/@supabase/storage-js@2526

@supabase/supabase-js

npm i https://pkg.pr.new/@supabase/supabase-js@2526

commit: 491cf3a

…types

coveralls · 2026-07-15T10:29:31Z

coverage: 80.568% (+0.04%) from 80.53% — fix/sb-key-format-check into master

…47960) Adds a contract test that runs `createProjectSupabaseClient()` against the real `@supabase/supabase-js` for each Supabase API key format (temporary, publishable, secret, legacy JWT), asserting that client construction succeeds. Also replaces the placeholder key fixtures in the existing unit tests with realistically shaped ones. Previously the tests mocked the SDK entirely and used keys that don't resemble real formats, so an SDK version that rejects a valid key at construction (as `@supabase/supabase-js` 2.110.4 and 2.110.5 did, reverted in #47945 and fixed in supabase/supabase-js#2526) passed CI unnoticed; with this test, such a regression fails on the dependency bump PR itself.  ## Summary by CodeRabbit * **Tests** * Added coverage confirming project clients work with temporary, publishable, secret, and legacy API key formats. * Updated test scenarios to use realistic temporary API key values.

@FrancoKaddour

This PR updates `@supabase/supabase-js` to v2.110.6. **Source**: supabase-js-stable-release --- ## Release Notes ## v2.110.6 ## 2.110.6 (2026-07-15) ### 🩹 Fixes - **postgrest:** type hinted self-referencing embeds as arrays ([#2520](supabase/supabase-js#2520)) - **realtime:** forward opts to send() in track() ([#2490](supabase/supabase-js#2490)) - **supabase:** warn instead of throw for unrecognized sb_ API key subtypes ([#2526](supabase/supabase-js#2526)) ### ❤️ Thank You - Franco Kaddour @FrancoKaddour - Katerina Skroumpelou @mandarini This PR was created automatically. Co-authored-by: supabase-workflow-trigger[bot] <266661614+supabase-workflow-trigger[bot]@users.noreply.github.com>

@FrancoKaddour

This PR updates @supabase/*-js libraries to version 2.110.6. **Source**: supabase-js-stable-release **Changes**: - Updated @supabase/supabase-js to 2.110.6 - Updated @supabase/auth-js to 2.110.6 - Updated @supabase/realtime-js to 2.110.6 - Updated @supabase/postgest-js to 2.110.6 - Refreshed pnpm-lock.yaml --- ## Release Notes ## v2.110.6 ## 2.110.6 (2026-07-15) ### 🩹 Fixes - **postgrest:** type hinted self-referencing embeds as arrays ([#2520](supabase/supabase-js#2520)) - **realtime:** forward opts to send() in track() ([#2490](supabase/supabase-js#2490)) - **supabase:** warn instead of throw for unrecognized sb_ API key subtypes ([#2526](supabase/supabase-js#2526)) ### ❤️ Thank You - Franco Kaddour @FrancoKaddour - Katerina Skroumpelou @mandarini ## v2.110.5 ## 2.110.5 (2026-07-14) ### 🩹 Fixes - **supabase:** avoid edge runtime warning ([#2522](supabase/supabase-js#2522)) ### ❤️ Thank You - Vaibhav @7ttp ## v2.110.4 ## 2.110.4 (2026-07-14) ### 🩹 Fixes - **functions:** stop sending API key in Authorization header for function calls ([#2511](supabase/supabase-js#2511)) - **realtime:** encode broadcast header fields as UTF-8 ([#2516](supabase/supabase-js#2516)) ### ❤️ Thank You - Katerina Skroumpelou @mandarini - Pedro Henrique ## v2.110.3 ## 2.110.3 (2026-07-13) ### 🩹 Fixes - **auth:** preserve pkce verifier ([#2513](supabase/supabase-js#2513)) - **postgrest:** pin tstyche target off floating latest ([#2509](supabase/supabase-js#2509)) ### ❤️ Thank You - Katerina Skroumpelou @mandarini - Vaibhav @7ttp ## v2.110.2 ## 2.110.2 (2026-07-09) ### 🩹 Fixes - **auth:** clear local session on signout failures ([#2504](supabase/supabase-js#2504)) ### ❤️ Thank You - Luc Peng This PR was created automatically. Co-authored-by: supabase-workflow-trigger[bot] <266661614+supabase-workflow-trigger[bot]@users.noreply.github.com>

github-actions Bot added the supabase-js Related to the supabase-js library. label Jul 15, 2026

mandarini self-assigned this Jul 15, 2026

fix(supabase): warn instead of throw for unrecognized sb_ API key sub…

c44d4a6

…types

mandarini force-pushed the fix/sb-key-format-check branch from 5fd614c to c44d4a6 Compare July 15, 2026 10:23

mandarini marked this pull request as ready for review July 15, 2026 10:24

mandarini requested a review from a team as a code owner July 15, 2026 10:24

depthfirst-app Bot reviewed Jul 15, 2026

View reviewed changes

Comment thread packages/core/supabase-js/src/lib/fetch.ts Outdated

mandarini mentioned this pull request Jul 15, 2026

test(studio): cover Supabase API key formats in project client tests supabase/supabase#47960

Merged

fix(supabase): address comment

491cf3a

grdsdev approved these changes Jul 15, 2026

View reviewed changes

mandarini merged commit c23e1ab into master Jul 15, 2026
30 checks passed

mandarini deleted the fix/sb-key-format-check branch July 15, 2026 13:12

supabase-supabase-autofixer Bot mentioned this pull request Jul 15, 2026

feat: update @supabase/*-js libraries to v2.110.6-canary.2 supabase/supabase#47967

Closed

supabase-libs-pr-manager Bot mentioned this pull request Jul 15, 2026

chore: update @supabase/supabase-js to v2.110.6 supabase/realtime#2025

Merged

supabase-supabase-autofixer Bot mentioned this pull request Jul 15, 2026

chore: update @supabase/supabase-js to v2.110.6 supabase/multiplayer.dev#77

Merged

supabase-libs-pr-manager Bot mentioned this pull request Jul 15, 2026

chore: update @supabase/supabase-js to v2.110.6 supabase/ssr#265

Merged

supabase-supabase-autofixer Bot mentioned this pull request Jul 15, 2026

feat: update @supabase/*-js libraries to v2.110.6 supabase/supabase#47968

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(supabase): warn instead of throw for unrecognized sb_ API key subtypes#2526

fix(supabase): warn instead of throw for unrecognized sb_ API key subtypes#2526
mandarini merged 2 commits into
masterfrom
fix/sb-key-format-check

mandarini commented Jul 15, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 15, 2026 •

edited

Loading

Summary by CodeRabbit

Walkthrough

Sequence Diagram(s)

Uh oh!

pkg-pr-new Bot commented Jul 15, 2026 •

edited

Loading

Uh oh!

Uh oh!

coveralls commented Jul 15, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

mandarini commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What changed?

Why was this change needed?

Screenshots/Examples

Breaking changes

Checklist

Additional notes

Uh oh!

coderabbitai Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Walkthrough

Sequence Diagram(s)

Uh oh!

pkg-pr-new Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

coveralls commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mandarini commented Jul 15, 2026 •

edited

Loading

coderabbitai Bot commented Jul 15, 2026 •

edited

Loading

pkg-pr-new Bot commented Jul 15, 2026 •

edited

Loading

coveralls commented Jul 15, 2026 •

edited

Loading