Events

Subscribe to SDK lifecycle events for analytics, logging, and custom UI state management.

The AuthenSee SDK emits events throughout the enrollment and authentication lifecycle. Use events for analytics tracking, custom UI state management, and debugging.

Subscribing to events

AuthenSee.on('auth.success', (event) => {
  console.log('Authentication succeeded:', event);
});

Unsubscribing

const handler = (event) => {
  console.log('Proof generating:', event);
};
 
AuthenSee.on('proof.generating', handler);
 
// Later:
AuthenSee.off('proof.generating', handler);

All events

type AuthenSeeEvent =
  | 'enrollment.started'
  | 'enrollment.complete'
  | 'enrollment.failed'
  | 'auth.started'
  | 'auth.success'
  | 'auth.failure'
  | 'factor.enrolled'
  | 'factor.updated'
  | 'proof.generating'
  | 'proof.complete';

Event reference

enrollment.started

Fired when the enrollment flow begins (after enroll() is called).

AuthenSee.on('enrollment.started', (event) => {
  // event.factorType: 'image_points' | 'passkey' | 'behavior_motion'
  console.log('Enrolling factor:', event.factorType);
});

enrollment.complete

Fired when enrollment finishes successfully. The Merkle root has been registered with the server.

AuthenSee.on('enrollment.complete', (event) => {
  // event.factorType: the enrolled factor type
  // event.merkleRoot: the committed root
  analytics.track('enrollment_complete', { factor: event.factorType });
});

enrollment.failed

Fired when enrollment fails (network error, invalid commitment, etc.).

AuthenSee.on('enrollment.failed', (event) => {
  // event.factorType: the factor that failed
  // event.error: AuthError with code and message
  console.error('Enrollment failed:', event.error.code);
});

auth.started

Fired when the authentication flow begins (after authenticate() is called). The SDK has requested a challenge from the server.

AuthenSee.on('auth.started', (event) => {
  showLoadingSpinner();
});

auth.success

Fired when authentication succeeds. The server has verified the proof and issued a JWT.

AuthenSee.on('auth.success', (event) => {
  // event.factorsVerified: FactorType[] — which factors were used
  // event.provingTimeMs: number — time spent generating the proof
  // event.token: string — the issued JWT
  analytics.track('authentication_success', {
    factorsVerified: event.factorsVerified,
    provingTimeMs: event.provingTimeMs,
  });
});

auth.failure

Fired when authentication fails (invalid proof, expired challenge, etc.).

AuthenSee.on('auth.failure', (event) => {
  // event.error: AuthError with code and message
  analytics.track('authentication_failure', {
    errorCode: event.error.code,
  });
});

factor.enrolled

Fired when a single factor is successfully enrolled (during multi-factor enrollment, this fires per factor).

AuthenSee.on('factor.enrolled', (event) => {
  // event.factorType: the specific factor that was enrolled
  console.log('Factor enrolled:', event.factorType);
});

factor.updated

Reserved for the proof-gated factor-rotation flow — updateFactor() currently throws (see Enrollment), so this event does not fire yet.

AuthenSee.on('factor.updated', (event) => {
  // event.factorType: the updated factor type
  console.log('Factor updated:', event.factorType);
});

proof.generating

Fired when the native prover starts generating a ZK proof. This is the most time-intensive step in the authentication flow. Use this to show a progress indicator.

AuthenSee.on('proof.generating', (event) => {
  // event.circuit: 'passkey_question_auth' | 'behavior_auth_passkey' | 'passkey_only_auth' | 'agent_keypair_auth'
  showProvingIndicator('Generating proof...');
});

proof.complete

Fired when the ZK proof has been generated on-device, before it is submitted to the server.

AuthenSee.on('proof.complete', (event) => {
  // event.provingTimeMs: number — time spent in the native prover
  // event.circuit: 'passkey_question_auth' | 'behavior_auth_passkey' | 'passkey_only_auth' | 'agent_keypair_auth'
  console.log(`Proof generated in ${event.provingTimeMs}ms`);
  hideProvingIndicator();
});

Example: full lifecycle tracking

AuthenSee.on('auth.started', () => {
  ui.showLoading('Verifying your identity...');
});
 
AuthenSee.on('proof.generating', () => {
  ui.updateLoading('Generating cryptographic proof...');
});
 
AuthenSee.on('proof.complete', (event) => {
  ui.updateLoading('Submitting proof for verification...');
  console.log(`Proof took ${event.provingTimeMs}ms`);
});
 
AuthenSee.on('auth.success', (event) => {
  ui.hideLoading();
  ui.showSuccess('Identity verified');
});
 
AuthenSee.on('auth.failure', (event) => {
  ui.hideLoading();
  ui.showError(`Verification failed: ${event.error.message}`);
});

UI components — useProofProgress() wraps these events as React state
Authentication — the flow these events narrate
Theming — styling the states you build from them