Disambiguate the API Keys feature from Clerk's Publishable and Secret Keys

[manovotny]

🔎 Previews:

• https://clerk.com/docs/pr/manovotny-single-rambutan/nextjs/getting-started/quickstart
• https://clerk.com/docs/pr/manovotny-single-rambutan/guides/development/clerk-environment-variables
• https://clerk.com/docs/pr/manovotny-single-rambutan/guides/development/machine-auth/api-keys
• https://clerk.com/docs/pr/manovotny-single-rambutan/reference/backend/api-keys/create
• https://clerk.com/docs/pr/manovotny-single-rambutan/reference/backend/api-keys/delete
• https://clerk.com/docs/pr/manovotny-single-rambutan/reference/backend/api-keys/get
• https://clerk.com/docs/pr/manovotny-single-rambutan/reference/backend/api-keys/list
• https://clerk.com/docs/pr/manovotny-single-rambutan/reference/backend/api-keys/revoke
• https://clerk.com/docs/pr/manovotny-single-rambutan/reference/backend/api-keys/update
• https://clerk.com/docs/pr/manovotny-single-rambutan/reference/backend/api-keys/verify

What does this solve? What changed?

"API keys" means two different things in the Clerk docs: the Publishable Key and Secret Key that connect your app to Clerk (copied from the API keys page in the Clerk Dashboard), and the API Keys feature that lets your users create keys for accessing your own app's API. Readers landing on either set of pages can easily conflate the two.

• Adds a new _partials/machine-auth/api-keys-disambiguation.mdx partial — a note pointing readers who are looking for their Publishable and Secret Keys to the Clerk Dashboard and the environment variables reference — and includes it on the API Keys guide and all seven JS Backend SDK apiKeys reference pages (create(), delete(), get(), list(), revoke(), update(), verify()).
• Adds the reverse-direction note to the Clerk environment variables reference, pointing readers who want user-generated keys to the API Keys feature.
• Mentions in the Next.js quickstart that, after claiming your keys, they're available any time on the API keys page in the Clerk Dashboard.

Deadline

• No rush

Other resources

• N/A

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Ready	Preview	Jul 3, 2026 4:25pm

[SarahSoutoul]

Noticed the callout note isn't in the getSecret() method but all the others? On purpose?

[manovotny]

Noticed the callout note isn't in the getSecret() method but all the others? On purpose?

Good catch — not on purpose. getSecret() was added on main in the Typedoc migration (#3445) after this branch was cut, so it missed the include when I merged main in. Added in 97932e5.