Flowless Docs

Appearance

Core Concepts ​

Understanding these core concepts will help you make the most of Flowless and integrate it effectively into your application.

Authentication vs. Authorization ​

Authentication ​

Authentication is the process of verifying who a user is. Flowless handles this completely:

  • User registration
  • Login (email/password, social OAuth)
  • Session creation and validation
  • Password reset
  • Email verification

Authorization ​

Authorization is the process of determining what a user can do. This is handled by your backend (Flowfull):

  • User roles and permissions
  • Access control to resources
  • Business logic rules
  • Feature flags

Key Point: Flowless tells you WHO the user is. Your backend decides WHAT they can do.

Sessions ​

What is a Session? ​

A session represents an authenticated user's connection to your application. When a user logs in, Flowless creates a session and returns a session_id.

Session Lifecycle ​

Session Properties ​

  • session_id: Unique identifier (e.g., ses_abcdefghijk)
  • user_id: Associated user
  • expires_at: Expiration timestamp (default: 7 days)
  • device_id: Optional device binding
  • ip_address: IP address (for validation)
  • user_agent: Browser/app identifier

Session Security ​

Sessions are secured using:

  • SHA-256 hashing - Session IDs are hashed before storage
  • Prefix system - ses_ for unhashed, hashed_ses_ for hashed
  • Expiration - Automatic cleanup of expired sessions
  • Device binding - Optional device-specific sessions
  • IP validation - Optional IP address validation

Trust Tokens ​

What are Trust Tokens? ​

Trust tokens are PASETO (Platform-Agnostic Security Tokens) that Flowless generates to securely communicate user information to your backend (Flowfull).

How They Work ​

Trust Token Contents ​

json
{
  "user_id": "usr_1234567890",
  "session_id": "ses_abcdefghijk",
  "email": "user@example.com",
  "name": "John Doe",
  "exp": 1733574000,
  "iat": 1733570400
}

Why Trust Tokens? ​

  • Security - Cryptographically signed, cannot be forged
  • Performance - Your backend can cache them
  • Stateless - No need to query Flowless for every request
  • Tamper-proof - Any modification invalidates the token

Bridge Validation ​

What is Bridge Validation? ​

Bridge validation is the process of your backend (Flowfull) validating a user's session with Flowless.

Validation Modes ​

Flowless supports three validation modes:

1. STANDARD (Default) ​

  • Validates session ID
  • Checks IP address
typescript
// Environment variable
VALIDATION_MODE=STANDARD

2. ADVANCED ​

  • Validates session ID
  • Checks IP address
  • Validates device ID
typescript
VALIDATION_MODE=ADVANCED

3. STRICT ​

  • Validates session ID
  • Checks IP address
  • Validates device ID
  • Validates user agent
typescript
VALIDATION_MODE=STRICT

Bridge Secret ​

Your backend authenticates with Flowless using a Bridge Secret:

bash
# In your Flowfull backend
BRIDGE_SECRET=your_secret_key_here

This secret is used to authenticate bridge validation requests.

Rate Limiting ​

What is Rate Limiting? ​

Rate limiting prevents abuse by limiting the number of requests a user or IP can make in a given time period.

Default Limits ​

EndpointLimitWindow
/auth/login5 requests15 minutes
/auth/register3 requests1 hour
/auth/password-reset3 requests1 hour
/auth/invalidate/me10 requests5 minutes
API calls100 requests1 minute

Rate Limit Headers ​

Flowless returns rate limit information in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1733570460

Handling Rate Limits ​

typescript
const response = await fetch('https://your-instance.pubflow.com/auth/login', {
  method: 'POST',
  // ...
});

if (response.status === 429) {
  const resetTime = response.headers.get('X-RateLimit-Reset');
  console.log(`Rate limited. Try again at ${new Date(resetTime * 1000)}`);
}

Email Verification ​

Why Email Verification? ​

Email verification ensures that:

  • Users own the email address they registered with
  • Reduces spam and fake accounts
  • Enables password reset functionality

Verification Flow ​

Configuration ​

You can configure email verification in the Pubflow dashboard:

  • Required - Users must verify before login
  • Optional - Users can login without verification
  • Disabled - No verification emails sent

Password Security ​

Password Requirements ​

Default requirements (configurable):

  • Minimum 8 characters
  • At least one uppercase letter
  • At least one lowercase letter
  • At least one number
  • At least one special character

Password Hashing ​

Flowless uses Argon2id for password hashing:

  • Industry-standard algorithm
  • Resistant to GPU attacks
  • Automatic salt generation
  • Configurable work factor

Password Reset Flow ​

Social Authentication (OAuth) ​

Supported Providers ​

Flowless supports OAuth 2.0 authentication with:

  • Google
  • Facebook
  • GitHub
  • Twitter
  • LinkedIn
  • Custom OAuth providers

OAuth Flow ​

Account Linking ​

Users can link multiple social accounts to one Flowless account:

  • Login with email/password, then link Google
  • Login with Google, then link Facebook
  • Unlink accounts at any time

Next Steps ​

Now that you understand the core concepts: