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
email	string?	Email (if email scope granted)
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, checkVaultStatus } from '@flowsta/holochain';

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

// Request identity linking
const result = await linkFlowstaIdentity({
  appName: 'YourApp',
  clientId: 'your_client_id',
  localAgentPubKey: myAgentKey,
});

// result.attestation contains the IsSamePersonEntry
console.log('Linked to Flowsta agent:', result.vaultAgentPubKey);

4. Commit the Attestation

The SDK commits an IsSamePersonEntry to your DHT automatically. Other agents on your network can verify the link:

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

// Query linked agents for any user
const links = await getLinkedAgents(agentPubKey);
// Returns all Flowsta-linked identities for this agent

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]

Next Steps for Holochain Apps

• Building Holochain Apps — Complete integration guide
• Agent Linking — Payload structure and verification
• Backups & CAL Compliance — Data portability requirements
• @flowsta/holochain SDK Reference — Full API reference
• IPC Reference — Direct IPC endpoint documentation

---

Desktop Tauri Apps

Building a Tauri desktop app without Holochain? Use @flowsta/auth-tauri for OAuth-style authentication through Flowsta Vault.

import { FlowstaAuthTauri } from '@flowsta/auth-tauri';

const auth = new FlowstaAuthTauri({
  clientId: 'your_client_id',
  appName: 'Your Desktop App',
});

const user = await auth.login();

Tauri Auth Guide →

---

Questions?

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