From f0f9bcb4c983c4e19daa73aeed3c0bee26e0b075 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 15 Oct 2025 20:36:39 +0000 Subject: [PATCH] docs: update TypeDoc documentation from clerk/javascript@d8948b8 --- .../backend/verify-machine-auth-token.mdx | 17 ++++++++++---- clerk-typedoc/backend/verify-token.mdx | 22 ++++++++++++------- .../types/sign-in-future-resource.mdx | 1 + 3 files changed, 28 insertions(+), 12 deletions(-) diff --git a/clerk-typedoc/backend/verify-machine-auth-token.mdx b/clerk-typedoc/backend/verify-machine-auth-token.mdx index 43fc12b40b..003154b7b8 100644 --- a/clerk-typedoc/backend/verify-machine-auth-token.mdx +++ b/clerk-typedoc/backend/verify-machine-auth-token.mdx @@ -2,10 +2,19 @@ Verifies any type of machine token by detecting its type from the prefix. ## Parameters -| Parameter | Type | Description | -| --------- | --------------------------------------------- | ------------------------------------------------------------------------- | -| `token` | `string` | The token to verify (e.g. starts with "m2m*", "oauth*", "api*key*", etc.) | -| `options` | [`VerifyTokenOptions`](#verify-token-options) | Options including secretKey for BAPI authorization | +| Parameter | Type | Description | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `token` | `string` | The token to verify (e.g. starts with "m2m*", "oauth*", "api*key*", etc.) | +| `options` | \{ apiUrl?: string; apiVersion?: string; audience?: string \| string[]; authorizedParties?: string[]; clockSkewInMs?: number; jwksCacheTtlInMs?: number; jwtKey?: string; secretKey?: string; skipJwksCache?: boolean; \} | Options including secretKey for BAPI authorization | +| `options.apiUrl?` | `string` | The [Clerk Backend API](/docs/reference/backend-api){{ target: '_blank' }} endpoint. Defaults to `'https://api.clerk.com'`. | +| `options.apiVersion?` | `string` | The version passed to the Clerk API. Defaults to `'v1'`. | +| `options.audience?` | string \| string[] | A string or list of [audiences](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3). If passed, it is checked against the `aud` claim in the token. | +| `options.authorizedParties?` | string[] | An allowlist of origins to verify against, to protect your application from the subdomain cookie leaking attack. Example: `['http://localhost:3000', 'https://example.com']`. | +| `options.clockSkewInMs?` | `number` | Specifies the allowed time difference (in milliseconds) between the Clerk server (which generates the token) and the clock of the user's application server when validating a token. Defaults to `5000`. | +| `options.jwksCacheTtlInMs?` | `number` | **Deprecated.** This cache TTL will be removed in the next major version. Specifying a cache TTL is a no-op. | +| `options.jwtKey?` | `string` | Used to verify the session token in a networkless manner. Supply the PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](/docs/guides/sessions/manual-jwt-verification). | +| `options.secretKey?` | `string` | The Clerk Secret Key from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. | +| `options.skipJwksCache?` | `boolean` | A flag to ignore the JWKS cache and always fetch JWKS before each JWT verification. | ## Returns diff --git a/clerk-typedoc/backend/verify-token.mdx b/clerk-typedoc/backend/verify-token.mdx index f723647902..7aab94ce0f 100644 --- a/clerk-typedoc/backend/verify-token.mdx +++ b/clerk-typedoc/backend/verify-token.mdx @@ -2,20 +2,26 @@ > This is a lower-level method intended for more advanced use-cases. It's recommended to use [`authenticateRequest()`](/docs/reference/backend/authenticate-request), which fully authenticates a token passed from the `request` object. ```ts -function verifyToken( - token: string, - options: VerifyTokenOptions, -): Promise>; +function verifyToken(token: string, options: { apiUrl?: string; apiVersion?: string; audience?: string | string[]; authorizedParties?: string[]; clockSkewInMs?: number; jwksCacheTtlInMs?: number; jwtKey?: string; secretKey?: string; skipJwksCache?: boolean; }): Promise> ``` Verifies a Clerk-generated token signature. Networkless if the `jwtKey` is provided. Otherwise, performs a network call to retrieve the JWKS from the [Backend API](/docs/reference/backend-api/tag/JWKS#operation/GetJWKS){{ target: '_blank' }}. ## Parameters -| Parameter | Type | Description | -| --------- | --------------------------------------------- | -------------------------------- | -| `token` | `string` | The token to verify. | -| `options` | [`VerifyTokenOptions`](#verify-token-options) | Options for verifying the token. | +| Parameter | Type | Description | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `token` | `string` | The token to verify. | +| `options` | \{ apiUrl?: string; apiVersion?: string; audience?: string \| string[]; authorizedParties?: string[]; clockSkewInMs?: number; jwksCacheTtlInMs?: number; jwtKey?: string; secretKey?: string; skipJwksCache?: boolean; \} | Options for verifying the token. | +| `options.apiUrl?` | `string` | The [Clerk Backend API](/docs/reference/backend-api){{ target: '_blank' }} endpoint. Defaults to `'https://api.clerk.com'`. | +| `options.apiVersion?` | `string` | The version passed to the Clerk API. Defaults to `'v1'`. | +| `options.audience?` | string \| string[] | A string or list of [audiences](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3). If passed, it is checked against the `aud` claim in the token. | +| `options.authorizedParties?` | string[] | An allowlist of origins to verify against, to protect your application from the subdomain cookie leaking attack. Example: `['http://localhost:3000', 'https://example.com']`. | +| `options.clockSkewInMs?` | `number` | Specifies the allowed time difference (in milliseconds) between the Clerk server (which generates the token) and the clock of the user's application server when validating a token. Defaults to `5000`. | +| `options.jwksCacheTtlInMs?` | `number` | **Deprecated.** This cache TTL will be removed in the next major version. Specifying a cache TTL is a no-op. | +| `options.jwtKey?` | `string` | Used to verify the session token in a networkless manner. Supply the PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](/docs/guides/sessions/manual-jwt-verification). | +| `options.secretKey?` | `string` | The Clerk Secret Key from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. | +| `options.skipJwksCache?` | `boolean` | A flag to ignore the JWKS cache and always fetch JWKS before each JWT verification. | ## Example diff --git a/clerk-typedoc/types/sign-in-future-resource.mdx b/clerk-typedoc/types/sign-in-future-resource.mdx index b98a5fe064..a19c5433ac 100644 --- a/clerk-typedoc/types/sign-in-future-resource.mdx +++ b/clerk-typedoc/types/sign-in-future-resource.mdx @@ -25,6 +25,7 @@ and the creation of a new session. | `mfa.verifyBackupCode` | (params: SignInFutureBackupCodeVerifyParams) => Promise\<\{ error: unknown; \}\> | Used to verify a backup code as a second factor to sign-in | | `mfa.verifyPhoneCode` | (params: SignInFutureMFAPhoneCodeVerifyParams) => Promise\<\{ error: unknown; \}\> | Used to verify a phone code sent as a second factor to sign-in | | `mfa.verifyTOTP` | (params: SignInFutureTOTPVerifyParams) => Promise\<\{ error: unknown; \}\> | Used to verify a TOTP code as a second factor to sign-in | +| `passkey` | (params?: SignInFuturePasskeyParams) => Promise\<\{ error: unknown; \}\> | Initiates a passkey-based authentication flow, enabling users to authenticate using a previously registered passkey. When called without parameters, this method requires a prior call to `SignIn.create({ strategy: 'passkey' })` to initialize the sign-in context. This pattern is particularly useful in scenarios where the authentication strategy needs to be determined dynamically at runtime. | | `password` | (params: SignInFuturePasswordParams) => Promise\<\{ error: unknown; \}\> | Used to submit a password to sign-in. | | `phoneCode` | \{ sendCode: (params: SignInFuturePhoneCodeSendParams) => Promise\<\{ error: unknown; \}\>; verifyCode: (params: SignInFuturePhoneCodeVerifyParams) => Promise\<\{ error: unknown; \}\>; \} | - | | `phoneCode.sendCode` | (params: SignInFuturePhoneCodeSendParams) => Promise\<\{ error: unknown; \}\> | Used to send a phone code to sign-in |