## 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?
"Find your keys" offers only the Dashboard. Readers working from a
script, a preview branch, or a local stack have no path, which accounts
for several logged reports of people unable to locate a key.
## What is the new behavior?
Replace the procedure with a tabbed selector so a reader picks the path
that matches where they work:
- Dashboard, through the Connect dialog or Settings > API Keys.
- Supabase CLI, `supabase projects api-keys --project-ref`, including
the note that a preview branch has its own keys and needs its own ref.
- Management API, `GET /v1/projects/{ref}/api-keys?reveal=true`, for
deploy scripts and provisioning tooling.
- Local stack, from `supabase start` output or `supabase status`.
`queryGroup="retrieval-method"` makes each tab deep-linkable, so a
reader can be sent straight to one path.
## Additional context
PR 3 of 4. Base is #49796.
## Manual testing
1. Open the API keys guide on the deploy preview and find "Find your
keys".
2. Select each tab. One panel shows at a time, and the URL gains
`?retrieval-method=<tab>`.
3. Open that URL in a new tab. It restores the same selection.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Updated the API key deprecation guidance to link to the “Find your
keys” guide.
- Expanded the guide with instructions for retrieving keys through the
Dashboard, CLI, Management API, and local stack.
- Added guidance to create keys in the Dashboard when none are
available.
- Reworded the table of contents entry for improved clarity.
<!-- 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. Restructure, mostly moved lines, plus a tense fix in a
shared partial.
## What is the current behavior?
Context, procedure, and reference material are interleaved, so
background reading interrupts the action path.
- The page never states which key to use as an answer. You infer it from
a five-column reference table.
- Finding a key is a fragment inside an admonition, placed above the
page's own definition of an API key.
- Rotating a leaked key, the only procedure on the page, is the last H3.
- The "Changes to API keys" notice narrates a past change in future
tense, and "They will be deprecated" has no antecedent in its paragraph.
## What is the new behavior?
Group the guide into context, procedure, and reference sections, per
CONTRIBUTING § Guides on mixed information types.
- Lead with "Which key do you use?", a decision table keyed on where the
code runs. Section navigation sits directly below the intro.
- Collect the conceptual sections under "How API keys work" and give
publishable and secret keys parallel headings.
- Promote both procedures into "Find and use your keys". Rotation is now
an ordered procedure.
- Move the enumerated secret key rules into "Security reference",
grouped under bold labels by the kind of mistake each prevents, and
leave a short danger admonition where secret keys are introduced.
- Promote the five-sentence coexistence admonition to its own section.
Admonitions are for short warnings.
- Rewrite the shared deprecation partial for timeless documentation:
present tense, no dangling "They", no "now". The partial renders on five
pages.
- Pin a stable anchor on the rotation heading and update the one inbound
link, in the rotating-anon-service-and-jwt-secrets troubleshooting
entry.
- Align link text across docs for this guide. Twenty-one links pointed
at it under fourteen labels, including two that named the wrong
destination. Rule: when a link means the guide, the text is "API keys";
when it means a specific key or section, the specific text stays. Twelve
now share "API keys", up from three.
Review with `git diff --color-moved=zebra`.
## Additional context
PR 2 of 4. Base is #49795. Includes the link-text alignment previously
opened as #49866.
## Manual testing
1. Open the API keys guide on the deploy preview.
2. Check the table of contents. It shows three groups: How API keys
work, Find and use your keys, Security reference.
3. Open the rotating-anon-service-and-jwt-secrets troubleshooting entry
and follow "Rotate a leaked or compromised key" under Further readings.
It lands on the renamed heading.
4. Open the Realtime Broadcast guide and check the "Changes to API keys"
notice. It reads in present tense there too.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Updated API key guidance to explain the transition from legacy `anon`
and `service_role` keys to publishable and secret keys by the end of
2026.
- Reorganized the API keys guide with clearer key-selection guidance,
security recommendations, usage examples, and rotation steps.
- Updated troubleshooting references to point to the revised leaked-key
rotation guidance.
<!-- 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
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Consolidated API key deprecation guidance into a reusable notice for
consistent messaging across docs. Announces deprecation of legacy
anon/service_role JWT-secret keys by end of 2026, instructs switching to
sb_publishable_xxx / sb_secret_xxx, and provides steps to locate and
copy both new and legacy keys. Applied across auth, getting-started,
API, and realtime guides.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: fadymak <dev@fadymak.com>
Miranda Limonczenko