Configuration

The AuthenSeeConfig object is passed to AuthenSee.init() to configure the SDK. The only required field is sessionToken.

Full config reference

type AuthenSeeConfig = {
  /** Session token (sess_ prefix) created via POST /v1/sessions. Required. */
  sessionToken: string;
 
  /** AuthenSee server URL. */
  serverUrl: string;
 
  /** White-label theme configuration. */
  theme?: AuthenSeeTheme;
 
  /**
   * Headless mode: disables all built-in UI.
   * Use this when building a fully custom enrollment/auth experience.
   * Default: false
   */
  headless?: boolean;
 
  /**
   * Compiled Noir circuit JSON for real ZK proofs.
   * Optional — the SDK ships the circuit for every registered scheme
   * (passkey_question_auth, behavior_auth_passkey, passkey_only_auth,
   * agent_keypair_auth) bundled, and resolves the right one automatically
   * based on the scheme being proven. Override only when you need a
   * custom-compiled circuit.
   */
  circuitJson?: object;
 
  /**
   * Force the MockProver instead of the WasmProver. Intended for tests
   * and local development where WASM is unavailable or undesired.
   * Default: false. Never enable in production.
   */
  mockProver?: boolean;
 
  /**
   * Enable debug logging.
   * When true, the SDK emits [AuthenSee] prefixed console logs
   * for every internal operation.
   * Default: false
   */
  debug?: boolean;
 
  /**
   * Circuit cache policy for ACIR bytecode and proving keys.
   * 'bundled' = ship with the app binary (default).
   * 'download' = download on first use and cache locally.
   * Default: 'bundled'
   */
  circuitCachePolicy?: 'bundled' | 'download';
 
  /**
   * Whether this persona is human.
   * Provider sets false for agent personas.
   * Agent personas use the agent_keypair_v1 scheme (a raw ECDSA-P256
   * keypair the agent controls) instead of a WebAuthn passkey ceremony.
   * Default: true
   */
  isHuman?: boolean;
};

Options detail

sessionToken

Required. A session token created on your backend via POST /v1/sessions using your secret key. Session tokens have a sess_ prefix and scope all SDK operations to a specific provider session.

await AuthenSee.init({
  sessionToken: 'sess_abc123def456',
  serverUrl: 'https://api.authensee.com',
});

See the API reference for how to create session tokens.

serverUrl

Required. The URL of your AuthenSee auth server instance.

Optional. Customize the SDK's built-in UI to match your brand. AuthenSeeTheme also carries the co-brand fields displayName, accent, and mode ('light' | 'dark' | 'auto'). See the theming guide for the full type, the co-brand model, and examples.

await AuthenSee.init({
  sessionToken: 'sess_abc123def456',
  serverUrl: 'https://api.authensee.com',
  theme: {
    colors: { primary: '#1e3a5f', primaryForeground: '#ffffff' },
    logo: 'https://app.example.com/logo.png',
    displayName: 'Aurora',
    accent: '#7c5cff',
    mode: 'dark',
  },
});

For the hosted flow specifically, the co-brand theme is configured on the admin Brand identity page and delivered on the session — and you launch it as a popup with @rebellion-systems/authensee-embed. See the embed guide.

headless

Default: false. When set to true, the SDK disables all built-in UI components. Use this when you want to build a fully custom enrollment and authentication experience using the SDK's logic methods directly.

In headless mode, you are responsible for:

Presenting questions to the user
Collecting answers
Displaying loading states during proof generation
Showing success/error states

circuitJson

Optional. The SDK ships the circuit for every registered scheme bundled and resolves the right one automatically based on the scheme being proven, so most integrators never need to set this field. Pass your own compiled artifact only if you need a custom-built circuit:

import circuit from './passkey_question_auth.json';
 
await AuthenSee.init({
  sessionToken: 'sess_abc123def456',
  serverUrl: 'https://api.authensee.com',
  circuitJson: circuit,
});

mockProver

Default: false. Forces the SDK to use the in-memory MockProver instead of loading the bundled circuit and the WASM prover. Use this in unit tests and dev environments where WASM is unavailable or you don't want real proof generation.

await AuthenSee.init({
  sessionToken: 'sess_test',
  serverUrl: 'http://localhost:3000',
  mockProver: true,
});

Never enable in production — proofs generated by MockProver will not verify against the real circuit.

debug

Default: false. When set to true, the SDK emits [AuthenSee] prefixed console logs for every internal operation — initialization, identity resolution, challenge requests, proof generation timing, and verification results.

await AuthenSee.init({
  sessionToken: 'sess_abc123def456',
  serverUrl: 'https://api.authensee.com',
  debug: true,
});
// Console output:
// [AuthenSee] init: connecting to https://api.authensee.com
// [AuthenSee] init: circuit loaded (bundled, 2.1MB)
// [AuthenSee] init: ready

Do not enable debug mode in production.

circuitCachePolicy

Default: 'bundled'. Controls how circuit artifacts (ACIR bytecode and proving keys) are loaded:

Value	Behavior
`'bundled'`	Circuit artifacts are shipped with your app binary. Fastest startup, larger app size.
`'download'`	Circuit artifacts are downloaded on first use and cached locally. Smaller app size, slower first run.

isHuman

Default: true. Set to false when authenticating AI agents. Agent personas enroll and authenticate with the agent_keypair_v1 scheme, which verifies a raw ECDSA-P256 keypair signature — there's no WebAuthn ceremony and no image-points or motion factor.

The agent_keypair_v1 scheme is restricted to personas flagged as agent. This prevents humans from downgrading to weaker authentication.

// For an AI agent
await AuthenSee.init({
  sessionToken: 'sess_agent_token_here',
  serverUrl: 'https://api.authensee.com',
  isHuman: false,
});

Theming — the full AuthenSeeTheme type and the co-brand model
Events — the lifecycle events debug mode logs
Sessions reference — where session tokens come from