@clerk/backend

Stop accepting the legacy cl_I7d4PD111III JWT category as a session or handshake token. Clerk no longer issues it, so authenticateRequest() now returns a signed-out state with reason token-type-mismatch for a token carrying it, the same as for other non-session categories.

Add webhook types for transactional email delivery, delays, bounces, complaints, failures, and suppressions. Bounce events distinguish Permanent, Transient, and Undetermined classifications. verifyWebhook() preserves the original event timestamp and instance ID for outcome handlers. These types prepare for the transactional email pilot; receiving the events requires the corresponding backend rollout.

Clarify issuer validation for session tokens and document that machine token verification ignores the issuer option.

Added an optional issuer option to verifyJwt(), verifyToken(), and authenticateRequest() to validate the JWT iss claim against a string or list of allowed strings. For verifyToken() and authenticateRequest(), this applies only to session tokens. Omitting issuer preserves existing behavior.

Add deprovisioned to the Backend User object and UserJSON, so you can tell when Directory Sync has deactivated a user, including in user.updated webhook payloads, without casting. It's separate from banned: Directory Sync sets and clears deprovisioned, while you set banned through the Dashboard or Backend API.

Add clerkClient.invitations.deleteInvitation(invitationId), which permanently deletes an instance invitation and the stored copies of its invitation email. Unlike revokeInvitation, this removes the invitation record itself, so it can be used to honor a data erasure request from someone who was invited but never signed up.

Verified OAuth access tokens now expose act, the RFC 8693 actor chain, when the token was issued by an OAuth 2.0 Token Exchange. It is available on the IdPOAuthAccessToken returned for both opaque and JWT access tokens.

SAML connections can trust several Identity Provider signing certificates at once. SamlConnection and EnterpriseConnection.samlConnection now include idpCertificates, every trusted certificate with its validity window, and createSamlConnection(), updateSamlConnection(), createEnterpriseConnection() and updateEnterpriseConnection() accept an idpCertificates array that replaces the connection's whole set. The single idpCertificate parameter is deprecated in favor of the array; it keeps working and still replaces the whole set.

Update the allowedOrigins JSDoc on clerkClient.instances.update() and the Instance resource to note that Electron apps using @clerk/electron also need the renderer's dev server origin, for example http://localhost:5173, during development.

Update the lockUser() JSDoc to link the Dashboard's current Protect rules page.

verifyWebhook() now returns the event's top-level timestamp (milliseconds since epoch when the event occurred) and instance_id, so webhook handlers can order events and identify the instance that sent them.

Update the allowedOrigins JSDoc for Electron apps to describe the custom renderer scheme used by @clerk/electron.

Capture authentication timezones so Clerk emails can display timestamps in a stored user timezone.

Add an optional nameQuery filter to oauthApplications.list() to search OAuth applications by name or exact client ID.

Fixes an issue where OAuth token validation did not correctly validate audience (aud) claims. Previous usages that specified audience were falsely passing. This upgrade will cause those to start rejecting if the audience indeed does not match the OAuth token's aud claim, including cases where the aud claim is omitted.

Expose the optional aud audience on verified OAuth access tokens.

Clarify domain API documentation and deletion parameter names. The active domain cannot be deleted.

Add experimental emails.createBatch() for submitting up to 100 transactional emails. Each message supports its own idempotency key and returns an independent success or error result.

Transactional messages now support sender and reply-to display names, cross-domain Reply-To addresses, CC/BCC recipients, attachments, and custom headers. These options require a backend deployment that supports them.

Update docs deep links in JSDoc comments to match clerk.com's new heading anchors (#get-token is now #gettoken, #o-auth-strategy is now #oauthstrategy, and so on).

Update the lockUser() JSDoc to point at the System page under Protect > Rules (/~/protect/rules/system), matching the Clerk Dashboard's Protect navigation.

Update Clerk Dashboard links in option descriptions, error messages, and READMEs to use the active-instance shortcut (https://dashboard.clerk.com/~/…) instead of the legacy /last-active?path=… URL.

Add experimental methods for sending and retrieving internal transactional emails, including Clerk suppression state and reasons.

Reject JWT-template tokens presented as session tokens in the Authorization header when acceptsToken is 'any' or an array that includes 'session_token'. authenticateRequest() now returns a signed-out state with reason token-type-mismatch for such a token, matching the existing acceptsToken: 'session_token' behavior.

Align JSDoc link targets with the docs link rules: internal docs links don't open in a new tab (removed {{ target: '_blank' }} from the Invitation Metadata link), while API reference links do (added it to the ExternalAccount Backend API link and the currentUser() endpoint link).

Mark the internal createBootstrapSignedOutState as deprecated. It is no longer used by @clerk/nextjs and is kept only for older published SDK versions.

Reject JWT-template tokens where a session or handshake token is expected. authenticateRequest() now returns a signed-out state with reason token-type-mismatch for such a token in the Authorization header or __session cookie. Tokens with no category tag, and instances configured to omit it, are unaffected.

Scope the JWKS cache per Clerk instance. The cache was keyed on the JWT kid alone and shared across the whole process, so an application verifying tokens for more than one Clerk instance (for example the Dynamic Keys / multi-tenant pattern) could resolve a signing key that was fetched for a different instance. Keys are now cached separately per secret key and API URL, so a token can only be verified against the instance whose credentials fetched its signing key.

Networkless verification with jwtKey had the same flaw: the JWK derived from the PEM was cached by kid alone, so a process verifying tokens with different jwtKey values could resolve a key derived from another instance's PEM. The JWK is now always derived from the jwtKey that was passed in.

The jwk-kid-mismatch error message no longer lists the key IDs currently held in the cache.

Fix Cookie header parsing in authenticateRequest() to follow RFC 6265 and guard against a non-string iss. Legitimate cookies and JWTs are unaffected.

Billing applied-discount snapshots now include optional durationInCycles. Payment attempt and statement UIs use the original discount length instead of cycles remaining, and omit the duration copy when it is unavailable.

Update the lockUser() documentation to link to the current Rules page in the Clerk Dashboard.

Use a root-relative link (/contact/support) for the passwordHasher "contact support" reference so the generated API reference renders it as an internal same-tab link instead of an external one.

Add clerkClient.users.removePassword(userId, params?) to remove a user's password through the Backend API. Password removal is allowed even when the user has no alternate sign-in method configured. Existing sessions remain active by default; pass { signOutOfOtherSessions: true } to revoke them.

Improve generated API reference links, expose BillingSubscriptionItemStatus, and clarify the createUser() identification status documentation.

Add the optional emailAddressIdentificationStatus and phoneNumberIdentificationStatus parameters to CreateUserParams. The Backend API has supported these arrays on POST /v1/users since they shipped, but createUser() had no way to pass them, so every email address and phone number was necessarily created verified. Each array runs parallel to emailAddress / phoneNumber — one item per identifier, applied by position — and an item set to 'reserved' creates that identifier unverified but still usable for sign-in and locked so no other user can claim it.

The createUser() documentation is corrected accordingly: it stated unconditionally that created email addresses and phone numbers are automatically verified, which is only the default.

Update fields for BillingSubscription and BillingSubscriptionItem

Return a TokenVerificationError from decodeJwt and verifyToken for tokens whose header, payload, or signature cannot be decoded.

Align the EnterpriseConnection response resource with what the Backend API actually returns: