Quick Start

Get up and running with Flowsta Auth in under 5 minutes. Choose your integration path:

Web Apps - OAuth SSO with @flowsta/auth
Desktop Holochain Apps - Identity linking with @flowsta/holochain

Both paths start with registering your app.

Prerequisites

Sign up at dev.flowsta.com
Create a new application
Copy your Client ID

No Client Secret Needed

Flowsta uses OAuth 2.0 with PKCE for web apps - no client secret required. Your Client ID is all you need.

See Register Your App for detailed setup instructions.

Web Apps

Add "Sign in with Flowsta" to any website or web application.

1. Configure Redirect URIs

In your app settings on the Developer Dashboard, add your redirect URIs:

http://localhost:3000/auth/callback    (development)
https://yourapp.com/auth/callback       (production)

2. Install the SDK

bash

npm install @flowsta/auth

typescript

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

const auth = new FlowstaAuth({
  clientId: 'your_client_id',
  redirectUri: window.location.origin + '/auth/callback'
});

// When user clicks "Sign in with Flowsta"
document.getElementById('login-btn').onclick = () => {
  auth.login();  // Redirects to login.flowsta.com
};

4. Handle the Callback

On your redirect URI page (/auth/callback):

typescript

const auth = new FlowstaAuth({
  clientId: 'your_client_id',
  redirectUri: window.location.origin + '/auth/callback'
});

try {
  const user = await auth.handleCallback();

  console.log('User ID:', user.id);
  console.log('Display Name:', user.displayName);
  console.log('DID:', user.did);

  window.location.href = '/dashboard';
} catch (error) {
  console.error('Login failed:', error.message);
}

5. Check Auth Status and Logout

typescript

// Check if user is logged in
if (auth.isAuthenticated()) {
  const user = auth.getUser();
  console.log('Welcome back,', user.displayName);
}

// Get the access token for API calls
const token = auth.getAccessToken();

// Logout - clears the SDK's local session (localStorage). Sign-out is per
// site: the user's Flowsta session on login.flowsta.com is theirs and stays.
auth.logout();

User Data

After authentication, you receive:

Field	Type	Description
`id`	`string`	Unique user ID (stable for the life of the identity) - key your own records on it
`email`	`string?`	Present only if you requested the `email` scope and the user shared an address at the consent screen (verified addresses only; deleted when they revoke your app). Design your app to work without it.
`username`	`string?`	Username (if set by user)
`displayName`	`string?`	Display name
`profilePicture`	`string?`	Profile picture - usually a `data:` URI, sometimes a URL
`agentPubKey`	`string?`	Holochain agent public key
`did`	`string?`	W3C Decentralized Identifier

Next Steps for Web Apps

Auth Overview - Complete OAuth flow documentation
Button Widget - Pre-built "Sign in with Flowsta" buttons
React / Vue / Qwik examples - Framework-specific guides
Security Guide - Best practices
@flowsta/auth SDK Reference - Full API reference

Desktop Holochain Apps

Let users prove their Flowsta identity on your Holochain app's DHT through agent linking.

Prerequisites

A Holochain application with its own DNA
A registered app at dev.flowsta.com - the Vault refuses a link request without a client_id
Users have Flowsta Vault installed on their desktop

1. Add Agent-Linking Zomes

Add the flowsta-agent-linking crates to your DNA, pinned to a release tag:

toml

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

toml

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

The crates pin exact HDK versions, so your DNA's hdi and hdk must be on the same Holochain line as the tag, or the build fails with trait-resolution errors:

Your DNA's Holochain	Tag	`hdi` / `hdk`
0.7.1	`v0.4.0` (integrity 0.3.0, coordinator 0.4.0; Rust 1.94+)	`=0.8.1` / `=0.7.1`
0.6.x	`v0.3.0` (integrity 0.2.0, coordinator 0.3.0)	`=0.7.0` / `=0.6.0`

Both tags keep working: the Vault's link signature is the same on either line, so your app moves to 0.7 when it is ready, not by a date.

yaml

# dna.yaml
integrity:
  zomes:
    - name: agent_linking_integrity
      bundled: ../../target/wasm32-unknown-unknown/release/flowsta_agent_linking_integrity.wasm
coordinator:
  zomes:
    - name: agent_linking
      bundled: ../../target/wasm32-unknown-unknown/release/flowsta_agent_linking_coordinator.wasm
      dependencies:
        - name: agent_linking_integrity

2. Install the SDK

bash

npm install @flowsta/holochain

3. Request Identity Linking

When a user wants to link their Flowsta identity:

typescript

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

// Check if Flowsta Vault is running
const status = await getVaultStatus();
if (!status.unlocked) {
  console.log('Please unlock Flowsta Vault first');
  return;
}

// Request identity linking - the user approves in their Vault
const result = await linkFlowstaIdentity({
  appName: 'YourApp',
  clientId: 'your_client_id',
  localAgentPubKey: myAgentKey,
});

console.log('Linked to Flowsta agent:', result.payload.vaultAgentPubKey);

Linking binds your app to that identity: one app agent links to one Flowsta identity, and a Vault that later holds a different identity is a stop, never a prompt to link again. See Identity switching.

4. Commit the Attestation

The Vault returns a signed payload; your app commits the IsSamePersonEntry attestation to your own DHT with a zome call:

typescript

import { decodeHashFromBase64 } from '@holochain/client';

// The Vault's signature arrives base64-encoded; the zome wants the raw 64 bytes.
const signatureBytes = (b64: string) =>
  Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));

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: signatureBytes(result.payload.vaultSignature),
  },
});

Anyone on your network can now verify the link - see Agent Linking for the verification recipe. To check link state later, use getFlowstaLinkStatus().

What Users See

When your app sends a link request, Flowsta Vault brings its window forward and shows an approval dialog with:

Your app name, and "by your organization" when your registration carries one
Requesting page - the origin the request came from
This app will be able to access: followed by the scopes you selected at dev.flowsta.com (for example "Decentralized ID (DID)", "Public key", "Display name")
"Your private key never leaves the vault."
Deny / Allow (or Update when your app re-links after changing its registration)

The user has 60 seconds to answer; then the request fails with timeout.

What you can also get from `@flowsta/holochain`

Once the agent-link is in place, the same SDK lights up:

User profile data (display name, profile picture, optional unique username) via getVaultStatus() - no signup forms or avatar uploads.
Automatic encrypted backups of your users' Holochain data to their Vault - see startAutoBackup.
One-click reinstall recovery - via restoreFromVault or seed adoption, your users' polls / games / messages / etc. follow them onto a new device, still authored by them.
CAL §4.2.1 data export out of the box - the Vault's Export (Your Data page) gives the user a portable JSON file with their cryptographic keys plus their data in plain English. The export a CAL-licensed Holochain app must provide; you write nothing.
Document signing via Sign It if you want cryptographic provenance for user-authored content - a linked app publishes to the Sign It network from the user's own device (SDK 3.6.0). See Sign It Developer Guide.

Next Steps for Holochain Apps

Building Holochain Apps - Complete integration guide
Identity Switching - What your app must do when one Vault holds several identities
Agent Linking - Payload structure and verification
Backups & Reinstall Recovery - Auto-backup + restore + CAL §4.2.1 in one pipeline
@flowsta/holochain SDK Reference - Full API reference
IPC Reference - Direct IPC endpoint documentation

Desktop Apps

Building a desktop app? Sign the user in through Flowsta Vault's local IPC with @flowsta/holochain - the user approves in the Vault, and your app never handles credentials.

typescript

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

// Your backend issues a random nonce (never a "flowsta-…" string); the Vault
// signs it and your backend verifies the signature with agentPubKey.
const { signature, agentPubKey, did } = await authenticateWithVault(nonce, {
  appName: 'YourApp',
});

Desktop App Authentication →

Questions?

Discord: Join our community
Support: Find out about Flowsta support options
GitHub: github.com/WeAreFlowsta

Quick Start ​

Prerequisites ​

Web Apps ​

1. Configure Redirect URIs ​

2. Install the SDK ​

3. Add the Login Button ​

4. Handle the Callback ​

5. Check Auth Status and Logout ​

User Data ​

Next Steps for Web Apps ​

Desktop Holochain Apps ​

Prerequisites ​

1. Add Agent-Linking Zomes ​

2. Install the SDK ​

3. Request Identity Linking ​

4. Commit the Attestation ​

What Users See ​

What you can also get from @flowsta/holochain ​

Next Steps for Holochain Apps ​

Desktop Apps ​

Questions? ​

Quick Start

Prerequisites

Web Apps

1. Configure Redirect URIs

2. Install the SDK

3. Add the Login Button

4. Handle the Callback

5. Check Auth Status and Logout

User Data

Next Steps for Web Apps

Desktop Holochain Apps

Prerequisites

1. Add Agent-Linking Zomes

2. Install the SDK

3. Request Identity Linking

4. Commit the Attestation

What Users See

What you can also get from `@flowsta/holochain`

Next Steps for Holochain Apps

Desktop Apps

Questions?