Flowless API Reference

Complete API documentation for Flowless Authentication Service. All endpoints use snake_case for request/response fields.

---

🚀 Quick Start

Base URL: https://your-instance-name.pubflow.com

Authentication: Most endpoints require X-Session-ID header or X-Bridge-Secret header (for bridge endpoints).

Response Format: All responses use snake_case fields (e.g., user_name, session_id, expires_at).

---

📚 API Endpoints by Category

🔐 Authentication

Core authentication endpoints for user login, registration, and logout.

• POST /auth/login - Login with email/username and password
• POST /auth/logout - Logout and invalidate session
• POST /auth/register/public - Register new user account (public registration)
• GET /auth/me - Get current authenticated user

---

👤 User Profile

Manage user profile information and profile pictures.

• PUT /auth/profile - Update user profile
• POST /auth/upload/picture - Upload profile picture
• DELETE /auth/upload/picture - Delete profile picture

---

🔑 Password Management

Password reset and change endpoints.

• POST /auth/password-reset/request - Request password reset email
• POST /auth/password-reset/validate - Validate reset token
• POST /auth/password-reset/complete - Complete password reset
• POST /auth/password-change/self - Change own password (authenticated)

---

✉️ Email Verification

Email verification and resend endpoints.

• POST /auth/resend-verification - Resend verification email

---

🔗 Sessions

Session validation and bridge integration endpoints.

• GET /auth/validation - Validate current session
• POST /auth/bridge/validate - Validate session for bridge integration

---

💾 Cache Management

Cache invalidation endpoints for efficient data synchronization.

• POST /auth/invalidate/me - Invalidate user cache to force fresh data

---

🎫 Token Auth

Token-based authentication for passwordless login via email/SMS.

• POST /auth/token/login - Create verification token (email/SMS)
• POST /auth/token/validate - Validate token (POST)
• GET /auth/token/validate - Validate token (GET)
• GET /auth/token/verify - Email verification link handler

---

🌐 Social Auth (BETA)

OAuth social authentication with Google, GitHub, Facebook, Apple, Discord, and Microsoft.

• GET /auth/social/{provider}/login - Start OAuth flow
• GET /auth/social/{provider}/callback - OAuth callback handler
• POST /auth/social/{provider}/login-api - API-based social login (mobile)
• GET /auth/social/providers - Get available providers
• GET /auth/social/accounts - Get linked social accounts
• DELETE /auth/social/accounts/{provider} - Unlink social account

---

👨‍💼 Admin

Admin-only endpoints for user management (requires admin or superadmin role).

• GET /auth/admin/users - Search and list users
• POST /auth/admin/users - Create new user
• GET /auth/admin/users/{user_id} - Get user details
• PUT /auth/admin/users/{user_id} - Update user
• POST /auth/password-change/admin - Change user password (admin)

---

🔒 Authentication Methods

Session Authentication

Most endpoints require a valid session. You can provide the session ID in multiple ways:

1. Header (Recommended):

X-Session-ID: ses_xyz123456

2. Query Parameter:

GET /auth/me?session_id=ses_xyz123456
POST /auth/profile?session_id=ses_xyz123456

3. Cookie:

Cookie: session_id=ses_xyz123456

Bridge Secret Authentication

Bridge endpoints (for integration) require the bridge secret:

X-Bridge-Secret: your-bridge-secret-key

---

📊 Rate Limiting

All endpoints are rate-limited to prevent abuse:

Endpoint Type	Limit	Window
Login	5 attempts	15 minutes
Registration	3 attempts	1 hour
Token Login	10 attempts	10 minutes
Token Validate	20 attempts	5 minutes
Social Login	10 attempts	15 minutes
Social API	20 attempts	10 minutes
Cache Invalidation	10 attempts	5 minutes
Admin Actions	50 attempts	10 minutes

Rate limit headers are included in responses:

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1733570460

---

🎯 Common Response Codes

Code	Description
200	Success
400	Bad Request - Invalid input or validation failed
401	Unauthorized - Invalid or missing authentication
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error
503	Service Unavailable - Feature not configured

---

🧪 Interactive Testing

Use the API Playground to test all endpoints interactively with your own server URL.

---

📖 Additional Resources

• Getting Started Guide - Setup and configuration
• Core Concepts - Understanding Flowless architecture
• Instance Setup - Deploy your own instance
• Social Auth Setup - Configure OAuth providers