Clerk Authentication - Frostline Docs

Overview

If your app uses Clerk for authentication, you need to configure a special sign-in flow so the Frostline agent can access your app during demos. Frostline uses ticket-based authentication to securely bypass your standard Clerk login flow only inside the demo environment. This allows the agent to enter your app as a predefined user without interacting with login UI or exposing credentials. This flow is built on top of Clerk’s official sign-in token mechanism. You can read more here

The accept-token page must be available at https://<your-domain>/accept-token. Any deviation from this path may lead to unexpected authentication failures.

How it works

Frostline generates a one-time Clerk sign-in ticket
The agent navigates to /accept-token?ticket=...
Your app exchanges the ticket for a Clerk session
The user is signed in and redirected into your app

This flow:

Uses Clerk’s supported authentication strategies
Does not expose passwords or secrets
Only runs inside the demo environment

Create the accept-token page

This page accepts the sign-in ticket from the query parameters, completes authentication with Clerk, and redirects the user into your app.

Next.js (App Router)

Create the following file:

"use client";

import { useSignIn, useUser } from "@repo/auth/client";
import { useRouter, useSearchParams } from "next/navigation";
import { Suspense, useEffect, useState } from "react";

function AcceptTokenContent() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const { signIn, setActive } = useSignIn();
  const { isSignedIn, user } = useUser();
  const searchParams = useSearchParams();
  const router = useRouter();

  const ticket = searchParams.get("ticket");

  useEffect(() => {
    if (!signIn || !setActive || !ticket || user || loading) return;

    const signInWithTicket = async () => {
      setLoading(true);
      try {
        const attempt = await signIn.create({
          strategy: "ticket",
          ticket,
        });

        if (attempt.status === "complete") {
          await setActive({
            session: attempt.createdSessionId,
          });
          router.push("/<your-app-home-page>"); // Redirect to your app's home page
        } else {
          setError("Authentication failed.");
        }
      } catch (err) {
        console.error(err);
        setError("Authentication failed.");
      } finally {
        setLoading(false);
      }
    };

    signInWithTicket();
  }, [signIn, setActive, ticket, user, loading, router]);

  if (!ticket) return <div>No token provided.</div>;
  if (loading) return <div>Signing you in…</div>;
  if (error) return <div>{error}</div>;

  return null;
}

export default function Page() {
  return (
    <Suspense fallback={<div>Loading…</div>}>
      <AcceptTokenContent />
    </Suspense>
  );
}

This page will:

Extract the ticket parameter from the URL
Authenticate the user using Clerk’s ticket strategy
Activate the session on success
Redirect the user into your app

Configure Clerk credentials

To generate sign-in tickets, Frostline needs access to Clerk credentials in the demo environment.

Required credentials

Clerk Secret Key
User ID (The user the agent will authenticate as during demos)

You can find:

Secret keys in Clerk Dashboard → API Keys
User IDs in Clerk Dashboard → Users

Demo environment configuration

Use Clerk development instance keys for your demo environment.Most Clerk projects automatically include:

A development instance
A production instance

If your app has a deployment using development Clerk keys, that deployment is ideal for Frostline demos.Why this is recommended:

The agent impersonates a non-production user
No interaction with real customer data
Safer for demos, recordings, and sales calls

Using production Clerk keys

There is no technical restriction on using production Clerk keys.However:

The agent will authenticate as a real production user
It may interact with real customer data
This can interfere with analytics, audits, or live users

If this behavior is acceptable for your use case, you may proceed — but we strongly recommend development instances when possible.

Security guarantees

The agent never sees your Clerk credentials
Secrets are stored encrypted
Credentials are injected only into a secure sandbox
Tokens are short-lived and single-use

This integration relies entirely on Clerk’s official authentication mechanisms and does not weaken your security model.

Introduction Email & Password

​Overview

​How it works

​Required credentials

​Demo environment configuration

​Using production Clerk keys

​Security guarantees

Overview

How it works

Required credentials

Demo environment configuration

Using production Clerk keys

Security guarantees