For Holochain Developers

Three ways to integrate Flowsta with your Holochain application.

Option 1: Authentication Only

Use Flowsta's OAuth for user authentication while managing your own Holochain infrastructure:

import { FlowstaAuth } from '@flowsta/auth';

const auth = new FlowstaAuth({
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  scopes: ['openid', 'public_key', 'did']
});

const user = await auth.handleCallback();
console.log('DID:', user.did);
console.log('Flowsta agent key:', user.agentPubKey);

Best for: Apps that want consistent user identity across the Flowsta ecosystem but run their own conductor and agent keys.

Option 2: Agent Linking via Vault

Let users prove their Flowsta identity on your DHT with cryptographic attestations:

import { linkFlowstaIdentity } from '@flowsta/holochain';

const result = await linkFlowstaIdentity({
  appName: 'YourApp',
  clientId: 'your-client-id',
  localAgentPubKey: myAgentKey,
});

// Commit to your DHT
await appWebsocket.callZome({
  role_name: 'my-role',
  zome_name: 'agent_linking',
  fn_name: 'create_external_link',
  payload: {
    external_agent: decodeHashFromBase64(result.payload.vaultAgentPubKey),
    external_signature: base64ToSignature(result.payload.vaultSignature),
  },
});

Best for: Apps where users need verifiable identity across multiple Holochain networks. Requires users to have Flowsta Vault installed.

Full guide: Building Holochain Apps

What you also get with Option 2

The agent-link is the foundation, but it's not the only thing the SDK gives you. Once your Holochain app is linked to Vault, the same SDK provides - for ~50 more lines total:

• The user's display name + profile picture + username via getVaultStatus(). Read once; no signup form, no avatar upload, no profile-management UI to build. Scope-gated at link time so the user controls what your app sees.
• Automatic encrypted backups of your users' Holochain data to their Vault, debounced after writes plus a heartbeat retry. The 50 MB / 10-snapshot capacity is yours - Vault handles the encryption, storage, and the user-facing Your Data UI.
• One-click reinstall recovery - when a user reinstalls your app, the SDK walks the Vault backup and replays each entry via a small dispatcher you write. Your users never lose data on a device wipe or move.
• CAL §4.2.1 data export out of the box - Vault's "Download Export" produces a portable JSON file with the user's cryptographic keys, your app's records as human-readable JSON, and the Cryptographic Autonomy License citation. The export your CAL-licensed app is obliged to provide; you write nothing.
• Document signing via the Sign It DNA if your app produces user-authored content worth signing - see Sign It Developer Guide. With sponsored signing, your organization's signing pool pays for app-initiated signatures instead of the user's personal quota - the Vault approval dialog tells the user so.

These compose: a public game in your app uses the player's display name + avatar; the next backup includes those names in the human-readable view; the CAL export inlines them alongside the user's keys.

See @flowsta/holochain SDK reference for the full API. ProofPoll is the live reference implementation - it uses every feature in this list.

Option 3: Desktop App via Vault Auth

Authenticate your desktop app through Vault's local IPC - no browser redirect, and your app never handles credentials:

import { getVaultStatus, authenticateWithVault } from '@flowsta/holochain';

const status = await getVaultStatus();
if (status.unlocked) {
  console.log('DID:', status.did);
  // Sign a server challenge to establish a session - see the Desktop guide
}

Best for: Desktop Holochain apps that want Flowsta authentication without browser redirects. Full guide →

Full guide: Tauri App Authentication

Electron Apps

Electron apps can use @flowsta/holochain directly - it communicates with Flowsta Vault over the same localhost IPC server (port 27777) and works in any JavaScript environment. No separate adapter is needed.

Adding Agent-Linking Zomes

To support Option 2, add the flowsta-agent-linking zomes to your DNA:

# integrity/Cargo.toml
[dependencies]
flowsta-agent-linking-integrity = { git = "https://github.com/WeAreFlowsta/flowsta-agent-linking" }

# coordinator/Cargo.toml
[dependencies]
flowsta-agent-linking-coordinator = { git = "https://github.com/WeAreFlowsta/flowsta-agent-linking" }

The zomes provide:

• create_external_link - Commit identity attestation
• get_linked_agents - Query linked agents
• are_agents_linked - Check if two agents are linked
• revoke_link - Revoke a link

Detailed zome reference

CAL Compliance

All Holochain apps are licensed under the Cryptographic Autonomy License (CAL), which requires that users can access their data and cryptographic keys. Flowsta Vault makes CAL compliance easy - integrate auto-backups so users can export their data at any time. The canonical-shape signature (v2.4.0+) dumps the user's source chain and runs your per-entry-type decoder, so backups stay human-readable and restorable:

import { startAutoBackup } from '@flowsta/holochain';

const backups = startAutoBackup({
  clientId: 'flowsta_app_abc123',
  appName: 'YourApp',
  adminWebsocket,                  // @holochain/client AdminWebsocket
  cellId: myCellId,                // your app's primary cell
  cellRoleName: 'my-role',
  agentPubKey: myAgentKey,         // Uint8Array
  decodeRecordForExport: async (entryType, entryBytesB64) => {
    // Decode one entry to plain JSON for the user's data export -
    // one match arm per entry type.
    return decodeMyEntry(entryType, entryBytesB64);
  },
});

// Call from zome-write success handlers (debounced internally):
backups.triggerBackupSoon();

// On sign-out / unmount:
backups.stop();

The returned controller has triggerBackupSoon() and stop(); a heartbeat retry runs every 30 minutes by default. The original getData-based signature (v2.3.0) still works for backwards compatibility, but new integrations should use the canonical shape - it unlocks per-entry-type counts in the Vault UI, readable CAL data exports, and one-click reinstall recovery.

If your app stores encrypted entries on the DHT, decrypt them in decodeRecordForExport so the user's export remains readable. The Vault encrypts backups at rest - no need to double-encrypt. Every time you add a new entry type, add a decoder arm for it.

Next Steps

• Building Holochain Apps - Step-by-step integration
• Agent Linking - Attestation mechanics
• Encrypted Entries - Private data on public DHT
• @flowsta/holochain SDK - Backup API reference
• Holochain Architecture - How Flowsta's infrastructure works