Skip to main content

​
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

  1. Frostline generates a one-time Clerk sign-in ticket
  2. The agent navigates to /accept-token?ticket=...
  3. Your app exchanges the ticket for a Clerk session
  4. 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
1

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.
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
2

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.