Why integrate Flowsta

Two integration paths. One user identity. Sign It in both.

Flowsta is identity infrastructure for apps that want to give users a sovereign, portable, cryptographic identity — without building each piece themselves. We offer two integration paths, and you pick the one that matches your app's architecture:

Web Apps & SaaS — OAuth 2.0 + PKCE through @flowsta/auth. No Vault install required.
Decentralized Holochain Apps — Vault-mediated agent linking through @flowsta/holochain. Runs on a local Holochain conductor.

Both paths surface the same Flowsta identity (DID, display name, profile picture, optional unique username). Users sign in once across the entire Flowsta ecosystem; you skip the signup flow, the profile-management UI, and the avatar-upload code. Both paths support Sign It, Flowsta's cryptographic document signing.

Path 1: Web Apps & SaaS (OAuth)

For: websites, SaaS dashboards, mobile apps, anything that can do a standard OAuth redirect. No Vault install required — works for users who have only signed up at flowsta.com.

SDK: @flowsta/auth (browser/Node.js, ~30 KB).

What you get

Feature	Detail
OAuth 2.0 + PKCE	Standard authorization code flow with PKCE — no client secret needed, safe to use in browser-only apps.
User profile in one round-trip	After login, `auth.getUser()` returns `id`, `email?`, `username?`, `displayName?`, `profilePicture?`, plus the user's `did` and `agentPubKey`. Scope-gated — you choose what to ask for.
No signup form to build	Users already have an account at flowsta.com. They click "Sign in with Flowsta", approve scopes, you get the profile data.
No password-reset support burden	Users manage their Flowsta password / recovery phrase at flowsta.com. You never see passwords; you never get reset emails.
Email permissions, granular	Users grant `email` scope per-app and can revoke it later from their Flowsta dashboard. Apps can request other scopes (`username`, `profile_picture`, etc.) the same way.
W3C DIDs out of the box	Every Flowsta user is a `did:flowsta:…`. Your app can use the DID as a stable, portable identifier across all integrations.
Cross-app identity	If the user has also linked the same identity to a Holochain app via Vault, your OAuth app sees the same DID and `agentPubKey` — same person, two paths.
Sign It support	`auth.signFile()` lets the user sign a document. Auto-detects whether to sign locally via Vault IPC (if Vault is installed) or remotely via Flowsta's signing API. See Sign It below.

What integration looks like

typescript

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

const auth = new FlowstaAuth({
  clientId: 'your_client_id',                  // from dev.flowsta.com
  redirectUri: 'https://yourapp.com/callback',
  scopes: ['openid', 'email', 'display_name', 'profile_picture'],
});

// Redirect to Flowsta login
auth.login();

// On your callback page
const user = await auth.handleCallback();
// { id, email, username, displayName, profilePicture, did, agentPubKey, signingMode }

console.log(`Welcome, ${user.displayName}`);

Quick Start: Web Apps →

Path 2: Decentralized Holochain Apps (Vault)

For: Holochain apps that run a local conductor (Tauri desktop, Electron, etc.). Users need Flowsta Vault installed.

SDK: @flowsta/holochain.

What you get

Feature	Detail
Agent linking attestation	The user signs a cryptographic attestation in their Vault that proves their Flowsta agent key and your app's local agent key belong to the same person. Stored on your app's DHT so any peer can verify.
User profile via `getVaultStatus()`	Display name, profile picture, and optional unique username — same data your OAuth integration gets, just over IPC instead of HTTP. Scope-gated. No signup form, no avatar upload, no profile-management UI to build.
Automatic encrypted backups	Your users' Holochain data backs up to their Vault on every write (debounced) plus a heartbeat retry. Encrypted with their device key — Flowsta can't read it.
One-click reinstall recovery	When the user reinstalls your app, the SDK walks the Vault backup and replays each entry via a small dispatcher you write. Users never lose data on a device wipe or move.
CAL §4.2.1 compliance out of the box	The user clicks "Download Export" in their Vault and gets a portable JSON file with their cryptographic keys, your app's records as human-readable JSON, and the Cryptographic Autonomy License citation — the export every CAL-licensed Holochain app is obliged to provide. You write nothing.
Cross-app identity attestations	A user who signs in to two Holochain apps via Vault has cryptographically-verifiable attestations on both DHTs proving "same person" — without trusting Flowsta as a central server.
Encrypted entries on the public DHT	Pattern for storing private data on the public DHT using lair-managed keys, with peers replicating ciphertext for resilience.
Sign It support	`signDocument()` over Vault IPC. The user approves in Vault; the signature is committed to the Signing DNA. See Sign It below.

What integration looks like

typescript

import {
  linkFlowstaIdentity,
  getVaultStatus,
  startAutoBackup,
  restoreFromVault,
  listVaultBackups,
} from '@flowsta/holochain';
import { invoke } from '@tauri-apps/api/core';

// 1. Link identity (one-time per install)
const result = await linkFlowstaIdentity({
  appName: 'YourApp',
  clientId: 'your_client_id',
  localAgentPubKey: myAgentKey,
});
await commitAttestationToDht(result.payload);

// 2. Read the user's Flowsta profile (no signup form needed)
const status = await getVaultStatus();
console.log(`Hi ${status.displayName} (@${status.webUsername})`);

// 3. Auto-backup the user's data
const controller = startAutoBackup({
  clientId, appName: 'YourApp',
  adminWebsocket, cellId, agentPubKey: myAgentBytes,
  cellRoleName: 'games',
  decodeRecordForExport: (entryType, entryB64) =>
    invoke('decode_record_for_export', { entryType, entryBytesB64: entryB64 }),
});
// Call after each zome write:
controller.triggerBackupSoon();

// 4. On reinstall, offer to restore
const backups = await listVaultBackups();
if (/* local data is empty AND backups.apps contains us */) {
  await restoreFromVault({
    clientId,
    dispatcher: async (record) =>
      invoke('restore_record', {
        entryType: record.entryType,
        entryBytesB64: record.raw_record.entry_b64,
      }),
  });
}

You also write two short Tauri commands (decode_record_for_export + restore_record) — one match per entry type, ~5 lines per arm using existing #[derive(Serialize, Deserialize)] on your entry structs. See the SDK Backups section for the full picture.

Building Holochain Apps → • Quick Start: Holochain Apps →

Sign It: document signing in both paths

Sign It is Flowsta's cryptographic document-signing layer — users sign a file's SHA-256 hash with their Ed25519 key, the signature is committed to a public Holochain DNA (the Signing DNA), and anyone with the file + the signer's agent public key can independently verify.

It's available from both integration paths, with the same end-user outcome and the same on-DHT signature record:

	Web / SaaS apps (`@flowsta/auth`)	Holochain apps (`@flowsta/holochain`)
API	`auth.signFile({ fileHash, intent })`	`signDocument({ fileHash, intent, … })`
How the user approves	If Vault is installed → IPC approval dialog. Otherwise → redirect to flowsta.com/sign for browser-based approval. SDK auto-detects (`user.signingMode`).	IPC approval dialog in Vault.
Where the signature lives	Committed to the Signing DNA by Flowsta's hosted conductor (remote mode) or the user's Vault (IPC mode). Either way: visible on the DHT.	Committed by the user's Vault. Same DNA, same DHT.
Content rights, integrity reports, perceptual hashing	All available in both paths.
Cross-device discoverability	A signature created in your web app is visible in the user's Vault Sign It tab and on flowsta.com — same identity, same DHT.	Same: visible in your app, the Vault, and at flowsta.com.

Sign It Overview → • Sign It Developer Guide →

Whichever path you pick, the user gets the same Flowsta identity and the same controls:

	OAuth	Holochain
W3C DID (`did:flowsta:…`) as the stable user identifier	✅	✅
Display name + profile picture + optional username	✅	✅
User can revoke at any time from their Flowsta dashboard	✅	✅
Scope-gated profile fields (user grants what your app sees)	✅	✅
Sign It for document signing	✅	✅
Cross-app identity (the same user across all their Flowsta-integrated apps)	✅	✅
No password handling, no password-reset emails to build	✅	✅
Holochain agent linking attestations on a DHT	—	✅
Automatic encrypted backups + reinstall recovery	—	✅
CAL §4.2.1-compliant user data export	—	✅
Encrypted private data on the public DHT	—	✅

If your app lives in a browser tab, take the OAuth path. If it runs a local Holochain conductor, take the Vault path. Either way, your user's Flowsta identity follows them.

Reference implementations

OAuth + Sign It in a SaaS: the flowsta.com dashboard itself uses @flowsta/auth.
Full Holochain integration: ProofPoll uses every feature of the Holochain path — agent linking, profile via getVaultStatus, canonical-shape backups, restore-on-first-launch, Sign It, encrypted entries on the DHT.

Next steps

Quick Start — 5-minute integration walkthroughs for both paths
Register Your App — set up your client_id and scopes at dev.flowsta.com
@flowsta/auth SDK — OAuth API reference
@flowsta/holochain SDK — Vault / Holochain API reference
Sign It — Document signing, available from both paths

Why integrate Flowsta ​

Path 1: Web Apps & SaaS (OAuth) ​

What you get ​

What integration looks like ​

Path 2: Decentralized Holochain Apps (Vault) ​

What you get ​

What integration looks like ​

Sign It: document signing in both paths ​

What both paths share ​

Reference implementations ​

Next steps ​

Why integrate Flowsta

Path 1: Web Apps & SaaS (OAuth)

What you get

What integration looks like

Path 2: Decentralized Holochain Apps (Vault)

What you get

What integration looks like

Sign It: document signing in both paths

What both paths share

Reference implementations

Next steps