Add SDK-specificity to Authentication flows, User management, and Session management sections #2595

alexisintech · 2025-09-12T17:17:35Z

🔎 Previews:

https://clerk.com/docs/pr/aa-sdk-specificity-project

⚠️ when #2730 is merged, update session tasks guide

Tip

Just to note that the most used SDKs in order: nextjs, react, express, expo, javascript, js backend

What changed?

Adds examples to support most SDKs. Remix is no longer supported so removes those examples. Go and Ruby have small userbases, so skips adding those.
Ensures links to /backend-api have {{ target: '_blank' }} following them

FIXES DOCS-11112

Checklist

I have clicked on "Files changed" and performed a thorough self-review
All existing checks pass

…in permissions Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

manovotny · 2025-10-28T21:26:18Z

docs/guides/users/reading.remix.mdx

+The [`getAuth()`](/docs/reference/remix/overview#get-auth) helper allows you to access the [`Auth` object](/docs/reference/backend/types/auth-object), which includes the current user's `userId` and the `isAuthenticated` property, which can be used to protect your routes.

-In the following example, the `userId` is passed to the JS Backend SDK's [`getUser()`](/docs/reference/backend/user/get-user){{ target: '_blank' }} method to get the user's full `User` object. For information on how to use the JS Backend SDK, see the [JS Backend documentation](/docs/js-backend/getting-started/quickstart){{ target: '_blank' }}.
+In the following example, the `userId` is passed to the JS Backend SDK's [`getUser()`](/docs/reference/backend/user/get-user) method to get the user's full `User` object. For information on how to use the JS Backend SDK, see the [reference documentation](/docs/js-backend/getting-started/quickstart).


Question: Why do all JS Backend SDK urls use /docs/js-backend/... except for /docs/reference/backend/...? Why isn't that one /docs/reference/js-backend/...?

Question: Why do all JS Backend SDK urls use /docs/js-backend/... except for /docs/reference/backend/...? Why isn't that one /docs/reference/js-backend/...?

because the quickstart doesn't live in /reference. it lives in getting-started/
and its a doc variant (its file is quickstart.js-backend.mdx), so it has js-backend injected into the path

manovotny · 2025-10-28T21:31:56Z

docs/reference/backend/authenticate-request.mdx

+  </Tab>
+</Tabs>
+
+### Networkless token verification


Should this file be using this partial instead?

hmm i'm confused what you mean. its using that partial there

I was saying, at first glance, the code here and the code in the partial looked the same. But it's not exactly. The import here is for Next.js and the partial is for backend. Plus one is using oauth_token and the otherjwtKey.

Again, it was a first glance thing. They looked the same. We can disregard.

docs/reference/nextjs/overview.mdx

manovotny · 2025-10-28T21:37:10Z

docs/reference/backend/user/create-user.mdx

+    "email_address": ["test@example.com"],
+    "password": "my-secure-password"
+  }'
+```


Should this have the <SignedIn> + "already injected" and <SignedOut> + "replace YOUR_SECRET_KEY" callouts?

manovotny · 2025-10-28T21:37:23Z

docs/reference/backend/user/delete-user.mdx

+
+```bash {{ filename: 'terminal' }}
+  curl 'https://api.clerk.com/v1/users/{user_id}' -X DELETE -H 'Authorization:Bearer {{secret}}' -H 'Content-Type:application/json'
+```


Should this have the <SignedIn> + "already injected" and <SignedOut> + "replace YOUR_SECRET_KEY" callouts?

manovotny · 2025-10-28T21:39:12Z

docs/reference/backend/user/update-user-metadata.mdx

+    "birthday": "1990-01-01"
+  }
+}' 'https://api.clerk.com/v1/users/{user_id}/metadata'
+```


Should this cURL:

Use {{secret}} instead of CLERK_SECRET_KEY

Use the <SignedIn> + "already injected" and <SignedOut> + "replace YOUR_SECRET_KEY" callouts?

manovotny · 2025-10-28T21:44:42Z

docs/reference/backend/user/update-user-metadata.mdx

+    ```ts {{ filename: 'public.ts' }}
+    import { getAuth, clerkClient } from '@clerk/express'
+
+    app.post('/updateBirthday', async (req, res) => {


This is the only POST in all the examples, which begs the question:

Should it be a GET for consistency

Technically, wouldn't using a POST, PUT, or PATCH in all of these be a more accurate method for performing an "update" action?

manovotny · 2025-10-28T21:55:06Z

docs/_partials/delete-user.mdx

+    export async function GET() {
+      const { userId } = await auth()
+
+      await clerkClient.users.deleteUser(userId)


Aren't all of these examples deleting yourself (the current logged in user)?

The previous examples were passing in a user to delete.

manovotny · 2025-10-28T21:56:50Z

docs/guides/users/managing.mdx

-    ```
-  </Tab>
-</Tabs>
+<Include src="_partials/delete-user" />


The previous example had a bash/cURL command, but the new partial does not.

Are we ok losing that or do we need to bring it back here or in the partial?

manovotny · 2025-10-28T22:06:27Z

docs/guides/users/managing.mdx

+To create a user programmatically, you can either [make a request directly to Clerk's Backend API](/docs/reference/backend/user/create-user#backend-api-bapi-endpoint) or use the [`createUser()`](/docs/reference/backend/user/create-user) method as shown in the following example.

-Use the following tabs to see examples of how to delete users using one of the following:
+<Include src="_partials/create-user" />


The previous example had a bash/cURL command, but the new partial does not.

Are we ok losing that or do we need to bring it back here or in the partial?

manovotny · 2025-10-28T22:13:50Z

docs/_partials/create-invitation.mdx

+    ```ts {{ filename: 'public.ts' }}
+    import { getAuth, clerkClient } from '@clerk/express'
+
+    app.post('/createUser', async (req, res) => {


This is the only POST in all the examples, which begs the question:

Should it be a GET for consistency

Technically, wouldn't using a POST in all of these be a more accurate method for performing an "create" action?

manovotny · 2025-10-28T22:15:24Z

docs/_partials/revoke-invitation.mdx

+    ```ts {{ filename: 'public.ts' }}
+    import { getAuth, clerkClient } from '@clerk/express'
+
+    app.post('/revokeInvitation', async (req, res) => {


This is the only POST in all the examples, which begs the question:

Should it be a GET for consistency

Technically, wouldn't using a POST or a DELETE in all of these be a more accurate method for performing an "revoke" action?

manovotny · 2025-10-28T22:16:42Z

docs/getting-started/quickstart.js-backend.mdx

+      </Tab>
+
+      <Tab>
+        If you are using Remix, see the following section for how to instantiate `clerkClient`.


Did you want to remove Remix here?

i don't think just yet - i'm not adding more remix examples, but want to keep most support for it since its in maintenance mode

docs/getting-started/quickstart.js-backend.mdx

manovotny · 2025-10-28T22:20:33Z

docs/getting-started/quickstart.js-backend.mdx

-            // Use `auth()` to access `isAuthenticated` and the user's ID
+            // The `Auth` object gives you access to properties like `isAuthenticated` and `userId`
+            // Accessing the `Auth` object differs depending on the SDK you're using
+            // https://clerk.com/docs/reference/backend/types/auth-object#how-to-access-the-auth-object


I like the helpfulness of adding a link here, but they are going to go unchecked if/when we do updates or redirects.

Because of that, should we leave them or remove them?

leave them because redirects will simply redirect the user to the intended page. the benefit of having them outweighs the con of a user possibly facing a redirect.

manovotny · 2025-10-28T22:29:53Z

docs/guides/configure/auth-strategies/social-connections/overview.mdx

+
+      // Use the JS Backend SDK to get the user's OAuth access token
+      const clerkResponse = await client.users.getUserOauthAccessToken(userId, provider)
+      const accessToken = clerkResponse.data[0].token || ''


The previous example was doing the same thing, but do we need to guard against data[0] here (and in all the examples below)? Will it ever not be an array? What if the userId is not found?

manovotny · 2025-10-28T22:32:30Z

docs/guides/configure/session-tasks.mdx

+<If sdk="nextjs">
+  For `auth.protect()`, signed-out users will be redirected to the sign-in page. In the following example, `pending` users will be redirected to the sign-in page, where the `<SignIn />` component will prompt them to fulfill the session tasks. Once finished, their session will move from `pending` to an `active` (signed-in) state.
+
+  ```tsx {{ filename: 'middleware.ts', mark: [[6, 8]] }}


Does this need to be proxy.ts now? If true, do we need to update Middleware references to Proxy in this file too?

manovotny · 2025-10-28T22:36:39Z

docs/guides/sessions/manual-jwt-verification.mdx

+  <Tab>
+    If you are using the [JS Backend SDK](/docs/js-backend/getting-started/quickstart) on its own, you need to provide the `secretKey` and `publishableKey` to `createClerkClient()` so that it is passed to `authenticateRequest()`. You can set these values as [environment variables](/docs/guides/development/clerk-environment-variables#clerk-publishable-and-secret-keys) and then pass them to the function.
+
+    <Include src="_partials/authenticate-req" />


Why is just this one in a partial and not the rest?

manovotny · 2025-10-28T23:38:23Z

docs/guides/users/inviting.mdx

 ## Create an invitation

-You can create an invitation in the [Clerk Dashboard](#using-clerk-dashboard) or [using the Backend API](#using-backend-api).
+You can create an invitation either in the [Clerk Dashboard](#in-the-clerk-dashboard) or [programmatically](#programmatically). When making this decision, keep in mind that if you create an invitation through the Clerk Dashboard, you can only set an invitation expiration date. If you create an invitation programatically, you are able to set more options, such as the URL you want the user to be redirected to after they accept the invitation, metadata to add to the invitation, or whether an invitation should be created if there is already an existing invitation for the given email address.


I understand that we're documenting how it currently works, but this feels like we should push to have these capabilities available via the dashboard too.

Co-authored-by: Michael Novotny <manovotny@gmail.com>

NWylynko and others added 30 commits July 17, 2025 14:12

bring in kyles scripts

4fd7d1b

support top level and nested items

28f40e2

add watch script

b62ccef

Add mapping generation to build ci

edeef17

run migration map checker in gh action

f288985

flip order

4349075

run on push to test ci

c3d5cc2

generate the manifest first

7da6b58

remove watch from tsx cli

d41ab9f

define flags in this repo instead of clerk/clerk

be7e558

Only enable ci on certain file changes

e8fb05c

disable feature flags

b22f559

fix up tests

c32a424

Potential fix for code scanning alert no. 10: Workflow does not conta…

7c8f48b

…in permissions Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

add support for 3rd level dropdown

b919b0f

Add a readme for new scripts

794d218

Add dotenv

8797e04

activate top-level manifest splitting and proposal generation

6d75db8

add support for icons in proposal.md. add more to proposal

2db149f

revise proposal

15b54b6

proposal checkpoint

e832559

proposal checkpoint

580f0d0

add sub top-level categories under reference

d1c0c09

update proposal from content tuple

5e5ef6e

progress checkin: mostly mappings

a33d50d

triage webhooks section

fe30e22

update

7d67070

work on the mapping script

cc98875

Add --fix arg

7a87a82

Add script for much better doc deletion

541bf8a

vercel bot deployed to Preview October 27, 2025 21:48 View deployment

remove ruby examples

0c03196

alexisintech changed the title ~~(WIP) Add SDK specificity across the docs~~ Add SDK-specificity to Authentication flows, User management, and Session management sections Oct 27, 2025

vercel bot deployed to Preview October 27, 2025 22:10 View deployment

alexisintech marked this pull request as ready for review October 27, 2025 22:50

alexisintech requested a review from a team as a code owner October 27, 2025 22:50

manovotny reviewed Oct 28, 2025

View reviewed changes

docs/reference/nextjs/overview.mdx Outdated Show resolved Hide resolved

manovotny reviewed Oct 28, 2025

View reviewed changes

docs/getting-started/quickstart.js-backend.mdx Show resolved Hide resolved

manovotny reviewed Oct 28, 2025

View reviewed changes

SarahSoutoul requested review from a team, NWylynko and SarahSoutoul October 29, 2025 18:57

Update docs/reference/nextjs/overview.mdx

b7b0854

Co-authored-by: Michael Novotny <manovotny@gmail.com>

vercel bot deployed to Preview October 29, 2025 22:10 View deployment

Add SDK-specificity to Authentication flows, User management, and Session management sections #2595

Are you sure you want to change the base?

Add SDK-specificity to Authentication flows, User management, and Session management sections #2595

Uh oh!

Conversation

alexisintech commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔎 Previews:

What changed?

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexisintech Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manovotny Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

manovotny Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

alexisintech commented Sep 12, 2025 •

edited

Loading

alexisintech Oct 29, 2025 •

edited

Loading

manovotny Oct 28, 2025 •

edited

Loading

manovotny Oct 28, 2025 •

edited

Loading