Flowsta SDK

Official JavaScript SDK for Flowsta Authentication - Zero-knowledge, OAuth-based Single Sign-On for web applications.

New to Flowsta? Create a developer account to get your Client ID.

📦 Packages

Package	Version	Description
@flowsta/auth ⭐	`2.0.0`	Core OAuth SDK with React bindings
@flowsta/login-button	`0.1.0`	Pre-built button components
@flowsta/holochain	`1.0.0`	Holochain integration

🚀 Getting Started

Prerequisites

Get your Client ID: Sign up at dev.flowsta.com
Add redirect URI: Configure https://yoursite.com/auth/callback in your app settings

Choose Your Integration Method

Option 1: NPM Package (Recommended)

Install the SDK for modern web apps:

npm install @flowsta/auth

Option 2: Pre-built Buttons

For quick integration with UI components:

npm install @flowsta/login-button

Supports: React, Vue, Qwik, Vanilla JS

Option 3: No Build Tools?

Use vanilla JavaScript without npm:

📖 Complete Vanilla JS Guide
🎨 Download Button Assets

Core SDK Features

@flowsta/auth

OAuth 2.0 authentication with PKCE - no client secrets needed.

Features:

✅ OAuth 2.0 + PKCE (Proof Key for Code Exchange)
✅ Zero-knowledge architecture - user data stays encrypted
✅ React bindings included (@flowsta/auth/react)
✅ TypeScript-first with full type safety
✅ Zero dependencies - lightweight (< 10kb)
✅ Works in any JavaScript environment

@flowsta/login-button

Pre-built "Sign in with Flowsta" button components.

Features:

✅ Multiple frameworks: React, Vue, Qwik, Vanilla JS
✅ 6 button variants (dark/light/neutral × pill/rectangle)
✅ Automatic PKCE generation and state management
✅ Customizable styling and behavior
✅ Inline SVG assets - works with any bundler

@flowsta/holochain

Sign Holochain actions using your Flowsta identity.

Features:

✅ Sign zome calls with Flowsta agent key
✅ Seamless Holochain integration
✅ TypeScript support

💡 Quick Start Examples

Vanilla JavaScript (No Build Tools)

Perfect for static HTML sites or simple projects:

<!DOCTYPE html>
<html>
<head>
  <title>Login with Flowsta</title>
</head>
<body>
  <a href="#" id="login-btn">
    <img src="https://docs.flowsta.com/buttons/svg/flowsta_signin_web_dark_pill.svg" 
         alt="Sign in with Flowsta" 
         width="175" height="40">
  </a>

  <script type="module">
    import { FlowstaAuth } from 'https://unpkg.com/@flowsta/auth';

    const auth = new FlowstaAuth({
      clientId: 'your-client-id',
      redirectUri: window.location.origin + '/callback.html'
    });

    document.getElementById('login-btn').addEventListener('click', (e) => {
      e.preventDefault();
      auth.login();
    });
  </script>
</body>
</html>

View Complete Vanilla JS Guide →

React with Hooks

Using the built-in React bindings:

import { FlowstaAuthProvider, useFlowstaAuth } from '@flowsta/auth/react';
import { FlowstaLoginButton } from '@flowsta/login-button/react';

function App() {
  return (
    <FlowstaAuthProvider
      clientId="your-client-id"
      redirectUri="https://yoursite.com/auth/callback"
    >
      <Dashboard />
    </FlowstaAuthProvider>
  );
}

function Dashboard() {
  const { isAuthenticated, user, login, logout } = useFlowstaAuth();
  
  if (!isAuthenticated) {
    return <FlowstaLoginButton onClick={login} variant="dark-pill" />;
  }
  
  return (
    <div>
      <h1>Welcome, {user?.displayName}!</h1>
      <p>@{user?.username}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

Vue 3 with Composition API

<script setup>
import { FlowstaAuth } from '@flowsta/auth';
import { FlowstaLoginButtonVue } from '@flowsta/login-button/vue';
import { ref, onMounted } from 'vue';

const auth = new FlowstaAuth({
  clientId: 'your-client-id',
  redirectUri: 'https://yoursite.com/callback'
});

const user = ref(null);
const isAuthenticated = ref(false);

onMounted(() => {
  isAuthenticated.value = auth.isAuthenticated();
  user.value = auth.getUser();
});

const login = () => auth.login();
const logout = () => {
  auth.logout();
  isAuthenticated.value = false;
  user.value = null;
};
</script>

<template>
  <div v-if="!isAuthenticated">
    <FlowstaLoginButtonVue
      client-id="your-client-id"
      redirect-uri="https://yoursite.com/callback"
      variant="dark-pill"
    />
  </div>
  <div v-else>
    <h1>Welcome, {{ user?.displayName }}!</h1>
    <button @click="logout">Logout</button>
  </div>
</template>

Core SDK (TypeScript)

For maximum control and flexibility:

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

const auth = new FlowstaAuth({
  clientId: 'your-client-id',
  redirectUri: 'https://yoursite.com/auth/callback',
  scopes: ['openid', 'email', 'display_name', 'username']
});

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

// On your callback page
try {
  const user = await auth.handleCallback();
  console.log('Authenticated:', user.displayName, user.username);
  // Redirect to dashboard
  window.location.href = '/dashboard';
} catch (error) {
  console.error('Authentication failed:', error);
  window.location.href = '/login?error=auth_failed';
}

🎨 Button Variants

The @flowsta/login-button package includes 6 official button styles:

Variant	Best For	Preview
`dark-pill`	Light backgrounds (recommended)
`dark-rectangle`	Light backgrounds, square style
`light-pill`	Dark backgrounds
`light-rectangle`	Dark backgrounds, square style
`neutral-pill`	Any background
`neutral-rectangle`	Any background, square style

Download all button assets →

👤 User Data & Scopes

After authentication, you'll receive a FlowstaUser object with the requested scopes:

interface FlowstaUser {
  sub: string;              // Unique user ID (always available)
  display_name?: string;    // Display name (if 'display_name' scope)
  username?: string;        // Username (if 'username' scope)
  email?: string;           // Email (if 'email' scope)
  email_verified?: boolean; // Email verification status
  profile_picture?: string; // Profile picture URL (if 'profile_picture' scope)
  agent_pub_key?: string;   // Holochain agent key (if 'public_key' scope)
  did?: string;             // Decentralized ID (if 'did' scope)
}

Available Scopes:

openid - Required, provides user ID
email - User's email address
display_name - User's display name
username - User's @username
profile_picture - Profile picture URL
public_key - Holochain agent public key
did - W3C Decentralized Identifier

🔐 What is Flowsta?

Flowsta provides zero-knowledge authentication powered by Holochain:

🔐 Zero-Knowledge: Your data is encrypted end-to-end - only you can decrypt it
🌐 Single Sign-On: One login works across all Flowsta-enabled applications
🔑 Decentralized Identity: Built on Holochain's DHT for censorship resistance
⚡ Easy Integration: Standard OAuth 2.0 with PKCE security
🛡️ Privacy-First: No tracking, no data mining, no selling your information

How It Works

User logs in via login.flowsta.com
Data is encrypted with user's password (zero-knowledge)
Stored on Holochain DHT (decentralized, censorship-resistant)
Your app receives an access token via OAuth
Fetch user data from the Auth API (decrypted on-demand)

📚 Documentation

Official Docs

Getting Started Guide - Complete setup tutorial
OAuth Quickstart - NPM integration guide
Vanilla JS Guide - No build tools required
Button Downloads - Download button assets
API Reference - Complete API docs
Security Guide - Best practices

Package READMEs

@flowsta/auth - Core SDK documentation
@flowsta/login-button - Button components
@flowsta/holochain - Holochain integration

Developer Resources

Developer Portal - Create apps, manage settings
Community Discord - Get help, share ideas
GitHub Issues - Report bugs

🗑️ Deprecated Packages (SDK 1.0)

The following packages are from SDK 1.0 and should not be used for new projects:

Package	Status	Replacement
`@flowsta/auth-sdk`	⚠️ Deprecated	Use `@flowsta/auth` (v2.0)
`@flowsta/auth-client`	⚠️ Deprecated	Use `@flowsta/auth` (v2.0)
`@flowsta/auth-react`	⚠️ Deprecated	Use `@flowsta/auth/react`
`@flowsta/auth-widgets`	⚠️ Deprecated	Not needed (OAuth-only in v2.0)

Why the migration? SDK 2.0 uses OAuth-only authentication for better security and simpler integration. No more email/password handling in your app!

🛠️ Development

Setup

# Clone the repository
git clone https://github.com/WeAreFlowsta/flowsta-sdk.git
cd flowsta-sdk

# Install dependencies
npm install

# Build all packages
npm run build

Available Scripts

npm run build       # Build all packages
npm run dev         # Watch mode for development
npm run test        # Run tests (coming soon)
npm run lint        # Lint code (coming soon)

Package Structure

sdk-monorepo/
├── packages/
│   ├── auth/              # Core OAuth SDK (v2.0)
│   ├── login-button/      # Pre-built button components
│   ├── holochain/         # Holochain signing integration
│   ├── core/              # [Deprecated] SDK 1.0 core
│   ├── client/            # [Deprecated] SDK 1.0 client
│   ├── react/             # [Deprecated] SDK 1.0 React
│   └── widgets/           # [Deprecated] SDK 1.0 widgets
└── README.md

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT © Flowsta

🔗 Links

Website: flowsta.com
Documentation: docs.flowsta.com
Developer Portal: dev.flowsta.com
GitHub: github.com/WeAreFlowsta/flowsta-sdk
npm: @flowsta

Questions? Join our Discord community or check out the documentation.

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github/workflows		.github/workflows
packages		packages
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

License

WeAreFlowsta/flowsta-sdk

Folders and files

Latest commit

History

Repository files navigation

Flowsta SDK

📦 Packages

🚀 Getting Started

Prerequisites

Choose Your Integration Method

Option 1: NPM Package (Recommended)

Option 2: Pre-built Buttons

Option 3: No Build Tools?

Core SDK Features

@flowsta/auth

@flowsta/login-button

@flowsta/holochain

💡 Quick Start Examples

Vanilla JavaScript (No Build Tools)

React with Hooks

Vue 3 with Composition API

Core SDK (TypeScript)

🎨 Button Variants

👤 User Data & Scopes

🔐 What is Flowsta?

How It Works

📚 Documentation

Official Docs

Package READMEs

Developer Resources

🗑️ Deprecated Packages (SDK 1.0)

🛠️ Development

Setup

Available Scripts

Package Structure

🤝 Contributing

📄 License

🔗 Links

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages