Quick Start

Get up and running with Flowsta Auth in under 5 minutes.

Step 1: Get Your Client ID

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, which means you don't need a client secret for browser or mobile apps. Your Client ID is all you need!

Step 2: Configure Your App

In your app's settings on the Developer Dashboard:

Add Redirect URIs

Add the URLs where users will be redirected after login:

http://localhost:3000/auth/callback    (for development)
https://yourapp.com/auth/callback       (for production)

Select Scopes

Choose which data your app needs:

• ✅ profile - User ID, display name, username, DID, profile picture
• ☐ email - Email address (requires user permission)

Step 3: Install the SDK

npm install @flowsta/auth

Or with yarn/pnpm:

yarn add @flowsta/auth
# or
pnpm add @flowsta/auth

Step 4: Add the Login Button

Create a login page that redirects to Flowsta:

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

const auth = new FlowstaAuth({
  clientId: 'your_client_id',
  redirectUri: 'https://yourapp.com/auth/callback',
  scopes: ['profile', 'email']  // Optional, defaults to ['profile', 'email']
});

// When user clicks "Sign in with Flowsta"
document.getElementById('login-btn').onclick = () => {
  auth.login();  // Redirects to login.flowsta.com
};

Step 5: Handle the Callback

On your redirect URI page (/auth/callback):

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

const auth = new FlowstaAuth({
  clientId: 'your_client_id',
  redirectUri: window.location.origin + '/auth/callback'
});

// Handle the OAuth callback
async function handleCallback() {
  try {
    const user = await auth.handleCallback();
    
    console.log('✅ Logged in successfully!');
    console.log('User ID:', user.id);
    console.log('Display Name:', user.displayName);
    console.log('Username:', user.username);
    console.log('DID:', user.did);
    
    // Redirect to your app
    window.location.href = '/dashboard';
  } catch (error) {
    console.error('❌ Login failed:', error.message);
    window.location.href = '/login?error=auth_failed';
  }
}

handleCallback();

Step 6: Check Authentication Status

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

Step 7: Logout

// Clear local session
auth.logout();

// Redirect to home
window.location.href = '/';

Complete Example

Here's a complete example that ties it all together:

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

const auth = new FlowstaAuth({
  clientId: 'your_client_id',
  redirectUri: window.location.origin + '/auth/callback'
});

// Check if already logged in
if (auth.isAuthenticated()) {
  const user = auth.getUser();
  showDashboard(user);
} else {
  showLoginButton();
}

function showLoginButton() {
  document.getElementById('login-btn').onclick = () => auth.login();
}

function showDashboard(user) {
  document.getElementById('welcome').textContent = `Welcome, ${user.displayName}!`;
  document.getElementById('username').textContent = user.username ? `@${user.username}` : '';
  document.getElementById('logout-btn').onclick = () => {
    auth.logout();
    window.location.href = '/';
  };
}

User Profile Data

After authentication, you'll have access to:

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

W3C Decentralized Identifiers (DIDs)

Every user automatically gets a W3C-compliant DID:

• Format: did:key:z6Mk... (based on Ed25519 public key)
• Self-sovereign: User owns it, not Flowsta
• Portable: Works across any DID-compatible system
• Verifiable: Cryptographically linked to user's keypair

Next Steps

Now that you have the basics working, explore more:

• OAuth Deep Dive - Complete OAuth flow documentation
• Button Widget - Pre-built "Sign in with Flowsta" buttons
• API Reference - Complete endpoint documentation
• Security Guide - Best practices and security patterns

Framework-Specific Guides

• React Integration
• Vue Integration
• Qwik Integration
• Vanilla JS

Having Issues?

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