feat(backend): Support ExpiresInSeconds param (#6150)

Author: jacekradko

.changeset/evil-paws-learn.md

@@ -0,0 +1,7 @@
+---
+'@clerk/backend': minor
+'@clerk/types': minor
+---
+
+Add support for `expiresInSeconds` parameter in session token generation. This allows setting custom expiration times for tokens both with and without templates via the backend API.
+

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -50,6 +50,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/reverification-config.mdx",
   "types/saml-strategy.mdx",
   "types/sdk-metadata.mdx",
+  "types/server-get-token-options.mdx",
+  "types/server-get-token.mdx",
   "types/session-resource.mdx",
   "types/session-status-claim.mdx",
   "types/session-verification-level.mdx",

packages/backend/src/api/__tests__/SessionApi.test.ts

@@ -0,0 +1,88 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server, validateHeaders } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('SessionAPI', () => {
+  const apiClient = createBackendApiClient({
+    apiUrl: 'https://api.clerk.test',
+    secretKey: 'deadbeef',
+  });
+
+  const sessionId = 'sess_123';
+  const mockTokenResponse = {
+    object: 'token',
+    jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.test.token',
+  };
+
+  describe('getToken', () => {
+    it('creates a session token without template', async () => {
+      server.use(
+        http.post(
+          `https://api.clerk.test/v1/sessions/${sessionId}/tokens`,
+          validateHeaders(async ({ request }) => {
+            const body = await request.text();
+            expect(body).toBe('');
+            return HttpResponse.json(mockTokenResponse);
+          }),
+        ),
+      );
+
+      const response = await apiClient.sessions.getToken(sessionId, '');
+      expect(response.jwt).toBe(mockTokenResponse.jwt);
+    });
+
+    it('creates a session token with template', async () => {
+      const template = 'custom-template';
+      server.use(
+        http.post(
+          `https://api.clerk.test/v1/sessions/${sessionId}/tokens/${template}`,
+          validateHeaders(async ({ request }) => {
+            const body = await request.text();
+            expect(body).toBe('');
+            return HttpResponse.json(mockTokenResponse);
+          }),
+        ),
+      );
+
+      const response = await apiClient.sessions.getToken(sessionId, template);
+      expect(response.jwt).toBe(mockTokenResponse.jwt);
+    });
+
+    it('creates a session token without template and with expiresInSeconds', async () => {
+      const expiresInSeconds = 3600;
+      server.use(
+        http.post(
+          `https://api.clerk.test/v1/sessions/${sessionId}/tokens`,
+          validateHeaders(async ({ request }) => {
+            const body = await request.json();
+            expect(body).toEqual({ expires_in_seconds: expiresInSeconds });
+            return HttpResponse.json(mockTokenResponse);
+          }),
+        ),
+      );
+
+      const response = await apiClient.sessions.getToken(sessionId, '', expiresInSeconds);
+      expect(response.jwt).toBe(mockTokenResponse.jwt);
+    });
+
+    it('creates a session token with template and expiresInSeconds', async () => {
+      const template = 'custom-template';
+      const expiresInSeconds = 3600;
+      server.use(
+        http.post(
+          `https://api.clerk.test/v1/sessions/${sessionId}/tokens/${template}`,
+          validateHeaders(async ({ request }) => {
+            const body = await request.json();
+            expect(body).toEqual({ expires_in_seconds: expiresInSeconds });
+            return HttpResponse.json(mockTokenResponse);
+          }),
+        ),
+      );
+
+      const response = await apiClient.sessions.getToken(sessionId, template, expiresInSeconds);
+      expect(response.jwt).toBe(mockTokenResponse.jwt);
+    });
+  });
+});

packages/backend/src/api/endpoints/SessionApi.ts

@@ -71,12 +71,35 @@ export class SessionAPI extends AbstractAPI {
     });
   }
 
-  public async getToken(sessionId: string, template: string) {
+  /**
+   * Retrieves a session token or generates a JWT using a specified template.
+   *
+   * @param sessionId - The ID of the session for which to generate the token
+   * @param template - Optional name of the JWT template configured in the Clerk Dashboard.
+   * @param expiresInSeconds - Optional expiration time for the token in seconds.
+   *   If not provided, uses the default expiration.
+   *
+   * @returns A promise that resolves to the generated token
+   *
+   * @throws {Error} When sessionId is invalid or empty
+   */
+  public async getToken(sessionId: string, template?: string, expiresInSeconds?: number) {
     this.requireId(sessionId);
-    return this.request<Token>({
+
+    const path = template
+      ? joinPaths(basePath, sessionId, 'tokens', template)
+      : joinPaths(basePath, sessionId, 'tokens');
+
+    const requestOptions: any = {
       method: 'POST',
-      path: joinPaths(basePath, sessionId, 'tokens', template || ''),
-    });
+      path,
+    };
+
+    if (expiresInSeconds !== undefined) {
+      requestOptions.bodyParams = { expires_in_seconds: expiresInSeconds };
+    }
+
+    return this.request<Token>(requestOptions);
   }
 
   public async refreshSession(sessionId: string, params: RefreshTokenParams & { format: 'token' }): Promise<Token>;

packages/backend/src/tokens/__tests__/authObjects.test.ts

@@ -1,6 +1,7 @@
 import type { JwtPayload } from '@clerk/types';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 
+import { createBackendApiClient } from '../../api/factory';
 import { mockTokens, mockVerificationResults } from '../../fixtures/machine';
 import type { AuthenticateContext } from '../authenticateContext';
 import type { InvalidTokenAuthObject, UnauthenticatedMachineObject } from '../authObjects';
@@ -13,6 +14,10 @@ import {
   unauthenticatedMachineObject,
 } from '../authObjects';
 
+vi.mock('../../api/factory', () => ({
+  createBackendApiClient: vi.fn(),
+}));
+
 describe('makeAuthObjectSerializable', () => {
   it('removes non-serializable props', () => {
     const authObject = signedOutAuthObject();
@@ -432,3 +437,80 @@ describe('getAuthObjectForAcceptedToken', () => {
     expect((result as UnauthenticatedMachineObject<'machine_token'>).id).toBeNull();
   });
 });
+
+describe('getToken with expiresInSeconds support', () => {
+  it('calls fetcher with expiresInSeconds when template is provided', async () => {
+    const mockGetToken = vi.fn().mockResolvedValue({ jwt: 'mocked-jwt-token' });
+    const mockApiClient = {
+      sessions: {
+        getToken: mockGetToken,
+      },
+    };
+
+    vi.mocked(createBackendApiClient).mockReturnValue(mockApiClient as any);
+
+    const mockAuthenticateContext = {
+      secretKey: 'sk_test_123',
+    } as AuthenticateContext;
+
+    const authObject = signedInAuthObject(mockAuthenticateContext, 'raw-session-token', {
+      sid: 'sess_123',
+      sub: 'user_123',
+    } as unknown as JwtPayload);
+
+    const result = await authObject.getToken({ template: 'custom-template', expiresInSeconds: 3600 });
+
+    expect(mockGetToken).toHaveBeenCalledWith('sess_123', 'custom-template', 3600);
+    expect(result).toBe('mocked-jwt-token');
+  });
+
+  it('calls fetcher without expiresInSeconds when template is provided but expiresInSeconds is undefined', async () => {
+    const mockGetToken = vi.fn().mockResolvedValue({ jwt: 'mocked-jwt-token' });
+    const mockApiClient = {
+      sessions: {
+        getToken: mockGetToken,
+      },
+    };
+
+    vi.mocked(createBackendApiClient).mockReturnValue(mockApiClient as any);
+
+    const mockAuthenticateContext = {
+      secretKey: 'sk_test_123',
+    } as AuthenticateContext;
+
+    const authObject = signedInAuthObject(mockAuthenticateContext, 'raw-session-token', {
+      sid: 'sess_123',
+      sub: 'user_123',
+    } as unknown as JwtPayload);
+
+    const result = await authObject.getToken({ template: 'custom-template' });
+
+    expect(mockGetToken).toHaveBeenCalledWith('sess_123', 'custom-template', undefined);
+    expect(result).toBe('mocked-jwt-token');
+  });
+
+  it('returns raw session token when no template is provided', async () => {
+    const mockGetToken = vi.fn();
+    const mockApiClient = {
+      sessions: {
+        getToken: mockGetToken,
+      },
+    };
+
+    vi.mocked(createBackendApiClient).mockReturnValue(mockApiClient as any);
+
+    const mockAuthenticateContext = {
+      secretKey: 'sk_test_123',
+    } as AuthenticateContext;
+
+    const authObject = signedInAuthObject(mockAuthenticateContext, 'raw-session-token', {
+      sid: 'sess_123',
+      sub: 'user_123',
+    } as unknown as JwtPayload);
+
+    const result = await authObject.getToken({});
+
+    expect(mockGetToken).not.toHaveBeenCalled();
+    expect(result).toBe('raw-session-token');
+  });
+});

packages/backend/src/tokens/authObjects.ts

@@ -189,7 +189,8 @@ export function signedInAuthObject(
   const getToken = createGetToken({
     sessionId,
     sessionToken,
-    fetcher: async (...args) => (await apiClient.sessions.getToken(...args)).jwt,
+    fetcher: async (sessionId, template, expiresInSeconds) =>
+      (await apiClient.sessions.getToken(sessionId, template || '', expiresInSeconds)).jwt,
   });
   return {
     tokenType: TokenType.SessionToken,
@@ -387,10 +388,37 @@ export const makeAuthObjectSerializable = <T extends Record<string, unknown>>(ob
   return rest as unknown as T;
 };
 
-type TokenFetcher = (sessionId: string, template: string) => Promise<string>;
+/**
+ * A function that fetches a session token from the Clerk API.
+ *
+ * @param sessionId - The ID of the session
+ * @param template - The JWT template name to use for token generation
+ * @param expiresInSeconds - Optional expiration time in seconds for the token
+ * @returns A promise that resolves to the token string
+ */
+type TokenFetcher = (sessionId: string, template?: string, expiresInSeconds?: number) => Promise<string>;
 
+/**
+ * Factory function type that creates a getToken function for auth objects.
+ *
+ * @param params - Configuration object containing session information and token fetcher
+ * @returns A ServerGetToken function that can be used to retrieve tokens
+ */
 type CreateGetToken = (params: { sessionId: string; sessionToken: string; fetcher: TokenFetcher }) => ServerGetToken;
 
+/**
+ * Creates a token retrieval function for authenticated sessions.
+ *
+ * This factory function returns a getToken function that can either return the raw session token
+ * or generate a JWT using a specified template with optional custom expiration.
+ *
+ * @param params - Configuration object
+ * @param params.sessionId - The session ID for token generation
+ * @param params.sessionToken - The raw session token to return when no template is specified
+ * @param params.fetcher - Function to fetch tokens from the Clerk API
+ *
+ * @returns A function that retrieves tokens based on the provided options
+ */
 const createGetToken: CreateGetToken = params => {
   const { fetcher, sessionToken, sessionId } = params || {};
 
@@ -399,8 +427,8 @@ const createGetToken: CreateGetToken = params => {
       return null;
     }
 
-    if (options.template) {
-      return fetcher(sessionId, options.template);
+    if (options.template || options.expiresInSeconds !== undefined) {
+      return fetcher(sessionId, options.template, options.expiresInSeconds);
     }
 
     return sessionToken;

packages/types/src/ssr.ts

@@ -5,7 +5,30 @@ import type { SessionResource } from './session';
 import type { UserResource } from './user';
 import type { Serializable } from './utils';
 
-export type ServerGetTokenOptions = { template?: string };
+/**
+ * Options for retrieving a session token.
+ */
+export type ServerGetTokenOptions = {
+  /**
+   * The name of a JWT template configured in the Clerk Dashboard.
+   * If provided, a JWT will be generated using the specified template.
+   * If not provided, the raw session token will be returned.
+   */
+  template?: string;
+  /**
+   * The expiration time for the token in seconds.
+   * If provided, the token will expire after the specified number of seconds.
+   * Must be a positive integer.
+   */
+  expiresInSeconds?: number;
+};
+
+/**
+ * A function that retrieves a session token or JWT template.
+ *
+ * @param options - Configuration options for token retrieval
+ * @returns A promise that resolves to the token string, or null if no session exists
+ */
 export type ServerGetToken = (options?: ServerGetTokenOptions) => Promise<string | null>;
 
 export type InitialState = Serializable<{