feat(backend): Add test session tokens endpoints

[tmilewski]

Description

Adds support for the Test Session Tokens API endpoint to the backend SDK. This allows developers to create test session tokens that can be used to impersonate users during testing or other automated flows.

Usage

import { createBackendApiClient } from '@clerk/backend';

const client = createBackendApiClient({ secretKey: 'sk_test_...' });

// Create a test session token
const testSessionToken = await client.testSessionTokens.create({
  userId: 'user_xxx',
  sessionMaxDurationInSeconds: 1800, // optional
});

// Access token properties
console.log(testSessionToken.token);
console.log(testSessionToken.url);
console.log(testSessionToken.status); // 'pending' | 'accepted' | 'revoked'

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• [] (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features
  • Introduced Test Session Tokens API to create tokens for impersonating users in automated testing and integration flows.
  • Tokens include lifecycle states (pending, accepted, revoked) and provide an acceptance URL to start a session.
  • Backend SDK now exposes the Test Session Tokens capability for programmatic creation and consumption of test tokens.

[changeset-bot]

🦋 Changeset detected

Latest commit: 2291c84

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
@clerk/backend	Minor
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 5, 2026 10:37pm

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7783

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7783

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7783

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7783

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7783

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7783

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7783

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7783

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7783

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7783

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7783

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7783

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7783

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7783

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7783

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7783

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7783

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7783

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7783

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7783

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7783

commit: 2291c84

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a Test Session Tokens API to the backend package: a new changeset entry; a TestSessionTokenAPI class with a create method accepting userId and optional sessionMaxDurationInSeconds and redirectUrl; a TestSessionToken resource class with fromJSON; JSON schema and ObjectType entry for test_session_token; deserializer handling for TestSessionToken; and index/factory exports wiring the new API into the client surface.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title 'feat(backend): Add test session tokens endpoints' clearly and concisely summarizes the main change of introducing Test Session Tokens API endpoints to the backend SDK.
Linked Issues check	✅ Passed	The pull request implements the primary objective of USER-4622 by adding complete support for Test Session Token endpoints in the backend SDK, including the API endpoint class, deserialization, and factory integration.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the Test Session Tokens API endpoints feature, with no unrelated or out-of-scope modifications detected in the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@packages/backend/src/api/endpoints/TestSessionTokenApi.ts`:
- Around line 1-18: Add unit/integration tests covering the new TestSessionToken
API: write tests that call TestSessionTokenAPI.create and assert the request
shape (method 'POST', path '/test_session_tokens', and bodyParams) and that the
response is correctly deserialized into the TestSessionToken type; use the
existing AbstractAPI test harness or mock the underlying request method
(spy/stub on AbstractAPI.request) to simulate API responses and verify
deserialization and error paths. Ensure to include at least one positive test
that returns a valid TestSessionToken payload and one negative test for error
handling.

In `@packages/backend/src/api/resources/TestSessionToken.ts`:
- Around line 3-24: Add JSDoc to the public TestSessionToken class and its
constructor parameters describing each field and the expected shape, and update
the static fromJSON(TestSessionTokenJSON) method to validate the incoming object
before constructing an instance: check required keys (id, user_id, token,
status, url, created_at, updated_at), verify types (strings for
id/user_id/token/url/status and numbers for timestamps), ensure status is one of
'pending'|'accepted'|'revoked', and throw a clear error if validation fails (or
call/annotate an upstream validator if validation is guaranteed there); keep the
constructor signature and internal property names as-is (TestSessionToken,
fromJSON, TestSessionTokenJSON).