Authentication - Circuit

This integration embeds Circuit’s authentication system directly into your app using an iframe that handles passkey authentication and returns session tokens to use with the API.

Authentication Flow

User sees a Circuit login interface embedded in your app
User authenticates using their passkey (fingerprint, face ID, etc.)
Circuit sends your app a session token via a secure message
Your app receives the token and can now call Circuit’s API
User is logged in with no redirects or popups

The session token acts like a key that unlocks Circuit’s wallet and agent API for that user.

Implementation Guide

HTML/JS Example
React Example

<!DOCTYPE html>
<html>
<head>
    <title>App + Circuit</title>
</head>
<body>
    <h1>Welcome to App + Circuit</h1>

    <!-- Status display -->
    <div id="auth-status">Click the button below to authenticate...</div>

    <!-- Circuit authentication iframe -->
    <iframe
        id="circuit-iframe"
        src="https://app.circuit.org/embed/auth/basic"
        width="400"
        height="500"
        style="border: none; border-radius: 12px; display: block; margin: 20px auto;">
    </iframe>

    <script>
        // This will store the session token later on receipt
        let circuitSessionToken = null;

        // Listen for messages from the Circuit iframe
        window.addEventListener('message', function(event) {
            // SECURITY: Only accept messages from Circuit's domain
            if (event.origin !== 'https://app.circuit.org') return;

            const messageType = event.data.type;
            const messagePayload = event.data.payload;

            // When Circuit iframe finishes loading and is ready
            if (messageType === 'ready') {
                document.getElementById('auth-status').textContent = 'Please authenticate';

                // Configure the iframe
                document.getElementById('circuit-iframe').contentWindow.postMessage({
                    type: 'configure',
                    config: {
                        backgroundColor: '#ffffff',
                        buttonColor: '#007bff',
                        buttonTextColor: '#ffffff',
                        title: 'Login to App + Circuit'
                    },
                    actionType: 'signIn',   // 'register' to register new user
                    username: 'username',   // Replace with actual username
                }, 'https://app.circuit.org');
            }

            // Getting the session token
            if (messageType === 'signInResult' || messageType === 'registerResult') {
                if (messagePayload.success) {
                    // SUCCESS! Get the session token
                    circuitSessionToken = messagePayload.authToken;

                    // Store it for later use
                    localStorage.setItem('circuitSessionToken', circuitSessionToken);

                    // Update the UI
                    document.getElementById('auth-status').textContent = 'Authentication successful';

                    // Now you can call Circuit API

                } else {
                    // Authentication failed
                    const errorMessage = messagePayload.error;
                    document.getElementById('auth-status').textContent = 'Authentication Failed: ' + errorMessage;

                    // Handle user not found error
                    if (errorMessage.includes('No matching passkey found')) {
                        // Try registration instead
                        document.getElementById('circuit-iframe').contentWindow.postMessage({
                            type: 'configure',
                            actionType: 'register',
                            username: 'username',
                            inviteCode: '', // Required for registration
                        }, 'https://app.circuit.org');
                    }
                }
            }
        });
    </script>
</body>
</html>

import { useEffect, useRef, useState } from 'react';

export default function App() {
    return (
        <div>
            <h1>My App</h1>
            <CircuitAuth username="testuser" /> // Replace with actual username
        </div>
    );
}

function CircuitAuth({ username }: { username: string }) {
    const iframeRef = useRef<HTMLIFrameElement>(null);
    const [status, setStatus] = useState('Loading...');
    const [tryingRegister, setTryingRegister] = useState(false);

    const configure = (actionType: 'signIn' | 'register') => {
        // Configure the iframe
        iframeRef.current?.contentWindow?.postMessage({
            type: 'configure',
            config: {
                backgroundColor: '#ffffff',
                buttonColor: '#007bff',
                buttonTextColor: '#ffffff',
                title: 'Login to App + Circuit'
            },
            actionType: actionType,
            username: username,
            inviteCode: actionType === 'register' ? '' : undefined, // Required for registration
        }, 'https://app.circuit.org');
    };

    useEffect(() => {
        // Listen for messages from the Circuit iframe
        const handleMessage = (event: MessageEvent) => {
            // SECURITY: Only accept messages from Circuit's domain
            if (event.origin !== 'https://app.circuit.org') return;

            const messageType = event.data.type;
            const messagePayload = event.data.payload;

            // When Circuit iframe finishes loading and is ready
            if (messageType === 'ready') {
                setStatus('Please authenticate');
                configure('signIn');
            }

            // Getting the session token
            if (messageType === 'signInResult' || messageType === 'registerResult') {
                if (messagePayload.success) {
                    // SUCCESS! Get the session token
                    const circuitSessionToken = messagePayload.authToken;

                    // Store session token for later use
                    localStorage.setItem('circuitSessionToken', circuitSessionToken);

                    // Update the UI
                    setStatus('Authentication successful');

                    // Now you can call Circuit API

                } else {
                    // Authentication failed
                    const errorMessage = messagePayload.error;
                    setStatus('Authentication failed: ' + errorMessage);

                    // Handle user not found error
                    if (errorMessage.includes("No matching passkey found") && !tryingRegister) {
                        // Try registration instead
                        setStatus("User not found, trying registration...");
                        setTryingRegister(true);
                        configure('register');
                    }
                }
            }
        };

        window.addEventListener('message', handleMessage);
        return () => window.removeEventListener('message', handleMessage);
    }, [username, tryingRegister]);

    return (
        <div>
            {/* Status display */}
            <p>{status}</p>

            {/* Circuit authentication iframe */}
            <iframe
                ref={iframeRef}
                src="https://app.circuit.org/embed/auth/basic"
                width="400"
                height="500"
                style={{ border: 'none', borderRadius: '12px' }}
            />
        </div>
    );
}

iframe Message Communication Protocol

Direction	Message Type	When Sent	Payload
Circuit → App	`ready`	iframe loaded	`{ version: '1.0.0' }`
App → Circuit	`configure`	After receiving ready	`json { actionType, username, inviteCode?, config? }`
Circuit → App	`signInResult`	Sign-in completed	`json { success: boolean, authToken?: string, error?: string }`
Circuit → App	`registerResult`	Registration completed	`json { success: boolean, authToken?: string, error?: string }`

Authentication Requirements

Action Type	Required Fields	Optional Fields
`signIn`	`username` (must exist)	`config`
`register`	`username` (must be unique)	`config`

iframe Structure

<iframe
    src="https://app.circuit.org/embed/auth/basic"
    width="400"
    height="500"
    style="border: none; border-radius: 12px;">
</iframe>

Configuration Options

Property	Type	Description	Example
`title`	`string`	Main heading text	`'Welcome to My App'`
`subtext`	`string`	Subtitle text	`'Sign in to continue'`
`ctaText`	`string`	Button text	`'Continue'`
`backgroundColor`	`string`	Background color	`'#ffffff'`
`buttonColor`	`string`	Button background color	`'#007bff'`
`buttonTextColor`	`string`	Button text color	`'#ffffff'`
`titleColor`	`string`	Title text color	`'#333333'`
`subtextColor`	`string`	Subtitle text color	`'#666666'`
`radius`	`number`	Border radius in pixels	`12`
`fontFamily`	`string`	Font family	`'sans-serif'`
`fontSize`	`string`	Font size	`'14px'`

Error Codes And Recovery

Error Message	What it Means	Recommended Action
`"No matching passkey found"`	User doesn’t exist in Circuit	User typo or registration
`"Username is already taken"`	Registration failed - username exists	Ask user for different username
`"Invalid invite code"`	Wrong or missing invite code	Verify the invite code is correct
`"Authentication verification failed"`	Passkey verification failed	Ask user to try again

Integration API

​Authentication Flow

​Implementation Guide

​iframe Message Communication Protocol

​Authentication Requirements

​iframe Structure

​Configuration Options

​Error Codes And Recovery