> ## Documentation Index
> Fetch the complete documentation index at: https://docs.circuit.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Passkey Authentication
> Embed Circuit's passkey authentication in your app using an iframe to get control-plane auth tokens for the Circuit API.
This integration embeds Circuit's authentication system directly into your app using an iframe that handles passkey authentication and returns control-plane auth tokens to use with the [control-plane REST API](./api/agents).
### Authentication Flow
1. User sees a Circuit login interface embedded in your app
2. User authenticates using their passkey (fingerprint, face ID, etc.)
3. Circuit sends your app an API auth token via a secure message
4. Your app receives the token and can now call Circuit's API
5. User is logged in with no redirects or popups
The API auth token authenticates Circuit API requests for that user. Wallet execution calls may also require a separate wallet execution permit.
### Implementation Guide
```javascript theme={null}
App + Circuit
Welcome to App + Circuit
Click the button below to authenticate...
```
```typescript theme={null}
import { useEffect, useRef, useState } from 'react';
export default function App() {
return (
My App
// Replace with actual username
);
}
function CircuitAuth({ username }: { username: string }) {
const iframeRef = useRef(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,
}, '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 API auth token
if (messageType === 'signInResult' || messageType === 'registerResult') {
if (messagePayload.success) {
// SUCCESS! Get the API auth token
const circuitApiAuthToken = messagePayload.sessionPermit;
// Store API auth token for later use
localStorage.setItem('circuitApiAuthToken', circuitApiAuthToken);
// 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 (
{/* Status display */}
{status}
{/* Circuit authentication iframe */}
);
}
```
### 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, config? } ` |
| Circuit → App | `signInResult` | Sign-in completed | `json { success: boolean, sessionPermit?: string, error?: string } ` |
| Circuit → App | `registerResult` | Registration completed | `json { success: boolean, sessionPermit?: string, error?: string } ` |
### Authentication Requirements
| Action Type | Required Fields | Optional Fields |
| ----------- | --------------------------- | --------------- |
| `signIn` | `username` (must exist) | `config` |
| `register` | `username` (must be unique) | `config` |
### iframe Structure
```javascript theme={null}
```
### 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 |
| `"Authentication verification failed"` | Passkey verification failed | Ask user to try again |
### Implementation Guide