Clerk Changelog

Key changes in v2 include a revamped structure for organization-related claims, now nested under the o claim for improved clarity and reduced token size. Additionally, a new v claim explicitly identifies the token version.

As of today, April 14, 2025, version 1 of the session token format is deprecated. You can update to version 2 via the Updates page⁠ in your Clerk Dashboard.

For a detailed breakdown of all claims available in v2 and how they differ from v1, please refer to our Session Tokens documentation.

We strongly recommend using one of our SDKs that support API version 2025-04-10 to handle decoding reliably.

Clerk is now supported as a Supabase third-party authentication provider⁠. This first-class integration allows Supabase to accept Clerk-signed session tokens, removing the need to create a custom JWT template and generate a specific token when interacting with Supabase's APIs.

Now, all you need to do is pass Clerk's session token to Supabase's client:

import { createClient } from '@supabase/supabase-js'
import { auth } from '@clerk/nextjs/server'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
  {
    async accessToken() {
      return (await auth()).getToken()
    },
  },
)

Enable the integration

To get started with Clerk and Supabase:

1. Visit the Clerk dashboard⁠ and go through the setup flow
2. Copy your Clerk instance domain into Supabase's Third-party auth settings⁠

For more information, visit the Supabase Integration documentation page. We can't wait to see what you build with Clerk and Supabase!

Reverification is officially out of beta and is a great way to protect sensitive actions by requiring users to provide a step-up verification.

As part of this release, we've also updated the <UserProfile /> component to require reverification for actions like password changes and email updates, you can find the complete list on our documentation⁠.

How it works

Our SDK includes straightforward hooks to manage reverification smoothly. Here's how to secure a Next.js server action:

'use server'

import { auth, reverificationError } from '@clerk/nextjs/server'

export const myAction = async () => {
  const { has } = await auth.protect()

  // Confirm the user's credentials have been recently verified
  const shouldUserRevalidate = !has({ reverification: 'strict' })

  // Prompt reverification if recent verification is missing
  if (shouldUserRevalidate) {
    return reverificationError('strict')
  }

  // Proceed if reverification is successful
  return { success: true }
}

'use client'

import { useReverification } from '@clerk/nextjs'
import { isReverificationCancelledError } from '@clerk/nextjs/errors'
import { myAction } from '../actions'

export default function Page() {
  const performAction = useReverification(myAction)

  const handleClick = async () => {
    try {
      const myData = await performAction()
      //     ^ this is typed as { success: boolean }
    } catch (error) {
      if (isReverificationCancelledError(error)) {
        // Handle the case where the user cancels reverification
      }

      // Handle any errors that occur during the action
    }
  }

  return <button onClick={handleClick}>Perform action</button>
}

Compatibility

• Support for Reverification is enabled for all new Clerk applications
• For existing applications that want to enable Reverification, you will need to activate the Reverification APIs within the Clerk Dashboard⁠
• Native and mobile app support within our SDKs is still actively underway and will be available soon

For all of the details around Reverification, explore our documentation.

This release includes both frontend (clerk_flutter⁠) and backend (clerk_backend_api⁠, clerk_auth⁠) packages, enabling developers to build secure, cross-platform applications with ease.

Key Features

• Complete Authentication Flow: Sign up, sign in, and manage user profiles directly from your Flutter code
• Organization Support: Full implementation of Clerk's organization features for managing multi-tenant applications
• Cross-Platform Compatibility: Works seamlessly across iOS, Android, and web platforms
• Type-Safe API: Built with Dart's strong typing system for better development experience
• Secure Backend Integration: Separate backend package for secure server-side operations

Getting Started

Add the package to your pubspec.yaml:

dependencies:
  clerk_flutter: ^0.0.8-beta

Flutter Implementation

Here's an example for how to initialize Clerk in your Flutter app:

class ExampleApp extends StatelessWidget {
  const ExampleApp({super.key, required this.publishableKey});

  final String publishableKey;

  @override
  Widget build(BuildContext context) {
    return ClerkAuth(
      config: ClerkAuthConfig(publishableKey: publishableKey),
      child: MaterialApp(
        theme: ThemeData.light(),
        debugShowCheckedModeBanner: false,
        home: Scaffold(
          body: SafeArea(
            child: ClerkErrorListener(
              child: ClerkAuthBuilder(
                signedInBuilder: (context, authState) {
                  return const ClerkUserButton();
                },
                signedOutBuilder: (context, authState) {
                  return const ClerkAuthentication();
                },
              ),
            ),
          ),
        ),
      ),
    );
  }
}

Server-side Usage

The clerk_auth package also allows interaction with Clerk via dart on the server side, if necessary:

import 'dart:io';

import 'package:clerk_auth/clerk_auth.dart';

Future<void> main() async {
  final auth = Auth(
    config: const AuthConfig(
      publishableKey: '<YOUR-PUBLISHABLE-KEY>',
    ),
    persistor: await DefaultPersistor.create(
      storageDirectory: Directory.current,
    ),
  );

  await auth.initialize();

  await auth.attemptSignIn(
    strategy: Strategy.password,
    identifier: '<USER-EMAIL>',
    password: '<PASSWORD>',
  );

  print('Signed in as ${auth.user}');

  await auth.signOut();

  auth.terminate();
}

Requirements

• Flutter >= 3.10.0
• Dart >= 3.0.0

Beta Status

This SDK is currently in beta. While we're confident in its functionality, we recommend:

• Hard pinning to the patch version in your pubspec.yaml
• Exercising caution before deploying to production
• Testing thoroughly in your development environment

Feedback

We welcome your feedback during this beta period. Please share your thoughts, report issues, or suggest improvements on our GitHub repository⁠.

Acknowledgments

Special thanks to DevAngels⁠ for their exceptional work in developing this SDK. Their expertise in Flutter development has been instrumental in bringing Clerk's authentication capabilities to the Flutter ecosystem.

Offer your users more peace of mind with email notifications for sign-ins from unfamiliar devices. This feature helps users identify potentially malicious activity and take action, such as revoking suspicious sessions.

How It Works

When a user signs in from an unrecognized device, Clerk sends an email notification to the account owner. The email includes essential details about the sign-in device, such as:

• Device type
• Operating system
• IP address
• Location
• Sign-in method

Like all emails delivered by Clerk, you can customize the template in the Clerk Dashboard⁠. And for supported instances, the email may also include a button to sign out from the unrecognized device immediately.

Get Started

New device sign-in emails are enabled by default for all new applications but are disabled by default for existing instances.

For more information, visit the Unauthorized Sign-In reference page in our docs.

We're excited to introduce our @clerk/agent-toolkit package, a new experimental package designed to integrate Clerk into your AI agent workflows. This toolkit empowers developers to build powerful agentic systems with support for managing users, user data, organizations, and more. It's designed to work seamlessly with frameworks like Vercel's AI SDK and LangChain.

Adding Clerk to your workflow is as simple as:

import { createClerkToolkit } from '@clerk/agent-toolkit/ai-sdk'
import { openai } from '@ai-sdk/openai'
import { streamText } from 'ai'
import { auth } from '@clerk/nextjs/server'

export async function POST(req: Request) {
  const { messages } = await req.json()

  // 1. Instantiate the toolkit
  const toolkit = await createClerkToolkit()

  const result = streamText({
    model: openai('gpt-4o'),
    messages,
    system: systemPrompt,
    // 2. Pass the tools to the model
    tools: toolkit.users(),
  })

  return result.toDataStreamResponse()
}

Running a local MCP server is just as easy:

npx -y @clerk/agent-toolkit -p local-mcp --secret-key sk_123

Key Features

• Vercel AI SDK & LangChain support: First-class support for Vercel's AI SDK and LangChain, with framework-specific helpers for each.
• Local MCP server support: The @clerk/agent-toolkit package comes with a standalone local MCP server so you can easily integrate Clerk with any MCP client such as Claude Desktop.
• Session context injection: Easily inject session claims (userId, sessionId, orgId) into system prompts for contextual awareness.
• Scoped helpers: Support for scoping actions to specific users or organizations to limit resource access.

Up Next

• Openai SDK support (coming soon): We're actively working on adding support for the openai SDK. Stay tuned for updates!

Try it today

Install the package using your preferred package manager and start building today:

npm install @clerk/agent-toolkit

Check out our example repository⁠ and the package's documentation⁠ to learn more.

We'd love to hear from you as you build. Your feedback will help shape the future of Clerk and AI. Reach out to ai@clerk.dev.