Login with Flowsta

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

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

Why Login 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

sequenceDiagram
    participant User
    participant YourApp as Your App
    participant Flowsta as Flowsta Auth
    participant User as User's Browser

    User->>YourApp: Clicks "Login with Flowsta"
    YourApp->>Flowsta: Redirect to login.flowsta.com
    Flowsta->>User: Shows login/signup page
    User->>Flowsta: Enters credentials
    Flowsta->>User: Shows consent screen
    User->>Flowsta: Approves access
    Flowsta->>YourApp: Redirects with auth code
    YourApp->>Flowsta: Exchanges code for token
    Flowsta->>YourApp: Returns access token
    YourApp->>Flowsta: Fetch user info
    Flowsta->>YourApp: Returns profile data
    YourApp->>User: User logged in!

OAuth 2.0 Flow

Login with Flowsta implements the OAuth 2.0 Authorization Code Flow with PKCE:

1. User clicks "Login 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

Scope	Description	User Data
profile	Basic profile information	userId, displayName, username, did, agentPubKey, profilePicture
email	Email address (requires explicit permission)	email, emailVerified

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 Login 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

   • profile (always available)
   • 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"
      scope="profile email"
      variant="dark_pill"
      onSuccess={(data) => console.log('Auth code:', data.code)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}

Vue 3

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

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

<template>
  <FlowstaLoginButtonVue
    client-id="your_client_id"
    redirect-uri="https://yourapp.com/auth/callback"
    scope="profile email"
    variant="dark_pill"
    @success="handleSuccess"
  />
</template>

Qwik

import { FlowstaLoginButtonQwik } 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 (
    <FlowstaLoginButtonQwik
      clientId="your_client_id"
      redirectUri="https://yourapp.com/auth/callback"
      scope="profile email"
      variant="dark_pill"
      onSuccess$={handleSuccess}
    />
  );
});

Vanilla JS

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

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

  const button = new FlowstaLoginButton({
    clientId: 'your_client_id',
    redirectUri: 'https://yourapp.com/auth/callback',
    scope: 'profile email',
    variant: 'dark_pill',
    onSuccess: (data) => console.log('Auth code:', data.code),
  });

  button.mount('#flowsta-login');
</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 login with Flowsta. 🎉

Next Steps

• Quickstart Guide - Detailed step-by-step tutorial
• Button Widget - Customize the login button
• API Reference - Complete OAuth endpoints
• Examples - Full app examples (React, Vue, Qwik, Node.js)
• Security - Best practices and security guide

Need Help?

• 📧 Email: support@flowsta.com
• 💬 Discord: Join our community
• 🐙 GitHub: github.com/WeAreFlowsta
• 📚 Docs: docs.flowsta.com