Sign in with Flowsta

Add "Sign in with Flowsta" to your application and let users sign in with their Flowsta account.

Similar to "Login with Google" or "Sign in with Apple," Sign in with Flowsta provides a seamless Single Sign-On (SSO) experience powered by OAuth 2.0 and built on decentralized infrastructure.

Why Sign in with Flowsta?

For Your Users

• ✅ One account, everywhere - Sign in across all Flowsta partner sites
• ✅ Privacy-first - Zero-knowledge architecture protects sensitive data
• ✅ No password fatigue - Remember one account, use it everywhere
• ✅ User control - Explicit permission required for email access
• ✅ W3C DIDs - Self-sovereign, portable identity

For Developers

• ✅ Quick integration - Add a button, configure OAuth, done
• ✅ Standard OAuth 2.0 - Industry-standard protocol with PKCE
• ✅ Multiple frameworks - React, Vue, Qwik, Vanilla JS support
• ✅ Beautiful UI - Pre-built login buttons and hosted auth pages
• ✅ Free tier - Get started without credit card

How It Works

OAuth 2.0 Flow

Sign in with Flowsta implements the OAuth 2.0 Authorization Code Flow with PKCE:

1. User clicks "Sign in with Flowsta" button
2. Your app redirects to login.flowsta.com
3. User authenticates (or signs up)
4. User grants consent for requested scopes
5. Flowsta redirects back with authorization code
6. Your backend exchanges code for access token
7. Your app fetches user profile data
8. User is logged in to your application

Features

🔐 Security

• OAuth 2.0 with PKCE - Protection against authorization code interception
• Refresh tokens - Long-lived sessions (30 days)
• Token revocation - Instant logout across devices
• Rate limiting - Protection against abuse
• Audit logging - Full security tracking

📧 Privacy-First Email Access

• Explicit consent required - Users must approve email access
• Zero-knowledge architecture - Email encrypted on Holochain
• Granular permissions - Users can revoke access anytime
• No email by default - Profile scope doesn't include email

🎨 Customization

• Pre-built buttons - Beautiful, responsive designs (light/dark/neutral)
• Hosted pages - Professional login and consent screens
• App branding - Add your logo, privacy policy, terms
• Custom scopes - Request only what you need

Available Scopes

Flowsta uses granular scopes so users only consent to the specific data your app needs:

Scope	Description	User Data
openid	User identifier (auto-included)	sub (user UUID)
display_name	Display name	name
username	Username	preferred_username
email	Email address	email, email_verified
profile_picture	Profile picture	profile_picture, has_custom_picture
did	Decentralized ID	did (W3C DID)
public_key	Public key	agent_pub_key (Holochain)
holochain	Holochain identity access	agent_pub_key in /userinfo

Request Only What You Need

Instead of requesting all profile data, choose only the scopes your app actually needs. This builds user trust and simplifies the consent screen.

Email Scope Requires Permission

The email scope requires explicit user permission. Users grant email access by clicking "Authorize" on the OAuth consent screen. Flowsta's zero-knowledge architecture ensures email is only shared with your app if the user explicitly approves it.

Quick Start

Get Sign in with Flowsta running in 5 minutes:

1. Create a Flowsta Developer Account

1. Go to dev.flowsta.com
2. Sign up or log in
3. Create a new application

2. Configure OAuth Settings

In your app's dashboard:

1. Add redirect URIs (where users return after login)

   https://yourapp.com/auth/callback

2. Select scopes your app needs

   • openid (auto-included, returns user ID)
   • display_name, username, profile_picture (profile data)
   • did, public_key (technical identifiers)
   • email (requires user permission)

3. Add branding (optional)

   • Logo URL
   • Privacy Policy URL
   • Terms of Service URL

3. Install the Button Widget

npm install @flowsta/login-button

4. Add the Button

React

import { FlowstaLoginButton } from '@flowsta/login-button/react';

function App() {
  return (
    <FlowstaLoginButton
      clientId="your_client_id"
      redirectUri="https://yourapp.com/auth/callback"
      scopes={['openid', 'email', 'display_name']}
      variant="dark-pill"
      onSuccess={(data) => console.log('Auth code:', data.code)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}

Vue 3

<script setup>
import { FlowstaLoginButton } from '@flowsta/login-button/vue';

const handleSuccess = (data) => {
  console.log('Auth code:', data.code);
};
</script>

<template>
  <FlowstaLoginButton
    client-id="your_client_id"
    redirect-uri="https://yourapp.com/auth/callback"
    :scopes="['openid', 'email', 'display_name']"
    variant="dark-pill"
    @success="handleSuccess"
  />
</template>

Qwik

import { FlowstaLoginButton } from '@flowsta/login-button/qwik';
import { $, component$ } from '@builder.io/qwik';

export default component$(() => {
  const handleSuccess = $((data: any) => {
    console.log('Auth code:', data.code);
  });

  return (
    <FlowstaLoginButton
      clientId="your_client_id"
      redirectUri="https://yourapp.com/auth/callback"
      scopes={['openid', 'email', 'display_name']}
      variant="dark-pill"
      onSuccess$={handleSuccess}
    />
  );
});

Vanilla JS

<div id="flowsta-login"></div>

<script type="module">
  import { initFlowstaLoginButton } from '@flowsta/login-button/vanilla';

  initFlowstaLoginButton('#flowsta-login', {
    clientId: 'your_client_id',
    redirectUri: 'https://yourapp.com/auth/callback',
    scopes: ['openid', 'email', 'display_name'],
    variant: 'dark-pill',
    onSuccess: (data) => console.log('Auth code:', data.code),
  });
</script>

5. Handle the Callback

When the user returns, exchange the authorization code for an access token:

// Exchange code for tokens (PKCE - no client secret needed!)
const response = await fetch('https://auth-api.flowsta.com/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: authorizationCode,
    redirect_uri: 'https://yourapp.com/auth/callback',
    client_id: 'your_client_id',
    code_verifier: storedCodeVerifier, // from PKCE flow
  }),
});

const { access_token, refresh_token } = await response.json();

No Client Secret Required

With PKCE, you don't need a client secret for browser or mobile apps. The code_verifier proves you initiated the request.

6. Fetch User Data

const userResponse = await fetch('https://auth-api.flowsta.com/oauth/userinfo', {
  headers: {
    'Authorization': `Bearer ${access_token}`,
  },
});

const user = await userResponse.json();
// { sub, name, preferred_username, did, agent_pub_key, profile_picture, email?, email_verified? }

That's it! Your users can now sign in with Flowsta. 🎉

Next Steps

• Quickstart Guide - Detailed step-by-step tutorial
• Button Widget - Customize the login button
• API Reference - Complete OAuth endpoints
• Security - Best practices and security guide
• Holochain Integration - Sign Holochain actions with Flowsta

Need Help?

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