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

1. Sign up at dev.flowsta.com
2. Create a new application
3. 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

npm install @flowsta/auth

3. Add the Login Button

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):

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

// 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
auth.logout();

User Data

After authentication, you receive:

Field	Type	Description
id	string	Unique user ID (stable for the life of the account)
email	string?	Almost always absent - Flowsta holds only a hash, so there's nothing to return even with the email scope. Ask the user if your app needs one.
username	string?	Username (if set by user)
displayName	string?	Display name
profilePicture	string?	Profile picture 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
• Users have Flowsta Vault installed on their desktop

1. Add Agent-Linking Zomes

Add the flowsta-agent-linking crate 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" }

Register the zomes in your DNA manifest:

# dna.yaml
integrity:
  zomes:
    - name: flowsta_agent_linking_integrity
coordinator:
  zomes:
    - name: flowsta_agent_linking
      dependencies:
        - name: flowsta_agent_linking_integrity

2. Install the SDK

npm install @flowsta/holochain

3. Request Identity Linking

When a user wants to link their Flowsta identity:

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);

4. Commit the Attestation

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

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),
  },
});

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 shows the user an approval dialog:

"YourApp" wants to link your Flowsta identity

This will create a cryptographic attestation proving your
Flowsta account is connected to your YourApp agent key.

[Deny]  [Allow]

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 - your users' polls / games / messages / etc. follow them onto a new device.
• CAL §4.2.1 data export out of the box - Vault's "Download Export" gives the user a portable JSON file with their cryptographic keys plus their data in plain English. The export every CAL-licensed Holochain app must provide; you write nothing.
• Document signing via Sign It if you want cryptographic provenance for user-authored content - see Sign It Developer Guide.

Next Steps for Holochain Apps

• Building Holochain Apps - Complete integration guide
• 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? Authenticate through Flowsta Vault's local IPC with @flowsta/holochain - the user approves in the Vault, and your app never handles credentials.

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

// Sign a server-issued challenge with the user's Vault identity
const { signature, agentPubKey } = await authenticateWithVault(challenge);

Desktop App Authentication →

---

Questions?

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