Start here
A Flowsta identity lives on the user's device, not on a server. Their 24-word recovery phrase deterministically derives their keys. The Flowsta Vault app holds those keys and a personal Holochain node. There is no account password on any server - the only password is the one that unlocks the Vault, and it stays on the device. When someone signs in to your app, their Vault signs a challenge and they approve it. Your app asks; the user answers. No one in between - not even Flowsta.
What are you building?
| Start with | You use | |
|---|---|---|
| A website or web app - "Sign in with Flowsta" through standard OAuth 2.0 + PKCE; nothing to install, users approve with their Vault. Add webhooks when your server needs to react to events. | Web apps | @flowsta/auth, @flowsta/login-button |
| A Holochain app - link your app's agent to a Flowsta identity, get the user's profile without a signup form, encrypted backups, reinstall recovery and the CAL export. | Holochain apps | @flowsta/holochain, the agent-linking zomes |
| A desktop app without Holochain - sign in through the Vault's local bridge, no browser redirect. | Desktop apps | @flowsta/holochain |
| Files people sign - authorship, approvals and content rights, verifiable by anyone. Works from either path above. | Sign It | signFile or signDocument |
Whatever you pick, you need a client_id: Register your app at dev.flowsta.com. The Quick Start walks the first ten minutes of each path.
How Flowsta works
Traditional authentication services put a company between your users and your app: a single point of failure, a credential store worth breaching, an authority that can close accounts, and user relationships locked in their system. Flowsta moves identity to the person.
| Traditional auth | Flowsta | |
|---|---|---|
| Where identity lives | Their database | The user's device |
| Credential on a server | Password hash | Nothing - a Vault identity has no server-side password |
| Identity standard | Proprietary user IDs | W3C DIDs (permanent - they never change) |
| Who approves a sign-in | The provider's session logic | The user, in their Vault |
| Privacy | Provider can read user data | Zero-knowledge - private records never leave the user's devices |
| Single point of failure | Yes | No - a distributed network with community-run nodes |
Three building blocks sit on that identity, and they share one mental model:
- Sovereign login - OAuth 2.0 + PKCE for web apps, the local Vault bridge for desktop apps. Either way, the user approves with keys only they hold.
- Sign It - cryptographic file signing and verification, approved per signature in the user's Vault, verifiable by anyone.
- Webhooks - HMAC-signed events so your server reacts to sign-ins and revocations the moment they happen.
The identity itself
- W3C DID:
did:flowsta:uhCAk..., based on the Ed25519 public key. Permanent for the life of the identity, across devices, restores and upgrades; an identity moved into the Vault from flowsta.com takes the DID of its Vault key when it moves, and the earlier DID resolves to it forever. Users own it, not Flowsta. Resolvable through Flowsta's DID resolver. - One identity, every path: sign in to any partner website with OAuth, link the same identity to any Holochain app through the Vault. Same DID and keys everywhere.
- Secure by default: Ed25519 keys, a 24-word BIP39 recovery phrase that restores the identity on any device, OAuth 2.0 + PKCE with no client secrets for web apps, and no server-side password - nothing to phish, leak or reset on any server. The Vault password never leaves the device.
What every path shares
| Web apps | Holochain apps | |
|---|---|---|
W3C DID (did:flowsta:…) as the stable user identifier | ✅ | ✅ |
| Display name, profile picture and optional username | ✅ | ✅ |
| The user can revoke your app at any time from their Flowsta dashboard | ✅ | ✅ |
| Scope-gated profile fields (the user grants what your app sees) | ✅ | ✅ |
| Sign It for document signing | ✅ | ✅ |
| Cross-app identity (the same person across all their Flowsta apps) | ✅ | ✅ |
| No password handling, no password-reset emails to build | ✅ | ✅ |
| Agent linking attestations on a DHT | - | ✅ |
| Automatic encrypted backups + reinstall recovery | - | ✅ |
| CAL §4.2.1 user data export | - | ✅ |
| Encrypted private data on a public DHT | - | ✅ |
If your app lives in a browser tab, take the web path. If it runs a local Holochain conductor, take the Holochain path. Either way, the user's Flowsta identity follows them.
About email
Flowsta's server holds only a hash of the user's email. The email scope asks the user to share the address held in their Vault at the consent screen. If they do, you receive email and email_verified (verified addresses only); if they revoke your app, the shared copy is deleted. Design your app to work without one.
Architecture
Flowsta uses three Holochain DNAs (Holochain 0.6.1):
| DNA | Purpose | Where it lives |
|---|---|---|
| Identity DNA (public, v1.4) | Public identity record | DID, agent public key, timestamps, site memberships, agent links - on the shared network. No display name or picture: those are served by Flowsta's API |
| Signing DNA (public, v1.4) | Document signing | File signatures, content rights, perceptual hashes, revocations - on the shared network |
| Private DNA (sealed, v2) | Sensitive data | Profile details, activity, app records - encrypted on the device before they are written; the DNA's network is the user's own devices only, so nothing reaches Flowsta or other users |
Zero-knowledge guarantee
Private records are sealed with keys derived from the recovery phrase and travel only between the user's own devices. Public data (the DID, signatures) is verifiable by anyone on Flowsta's tamper-proof network, built on Holochain.
The Vault is where all of this lives on the device. Security & Privacy says what the server holds, what the Vault sends home, and how data leaves with the user. Architecture covers the nodes and versions.
Reference implementations
- ProofPoll (MIT) - a Holochain app with agent linking, the profile from the Vault, canonical-shape backups, seed escrow with authorship-preserving restore, and one profile per Flowsta identity.
Questions?
- Discord: Join our community
- Support: Flowsta support options
- GitHub: github.com/WeAreFlowsta