🎮 Interactive API Playground
Test all Flowless authentication endpoints with a fully interactive playground. Try requests directly from your browser!
📖 Live API Testing
All endpoints are interactive with real-time request/response testing. Change parameters, headers, and body content to see how the API responds.
� Quick Start
- Select an endpoint from the list below
- Fill in the required parameters
- Click "Try it out" to send the request
- View the response in real-time
Complete authentication backend for modern applications. Flowless provides managed authentication with session management, social login, password reset, and more.
Contact
Servers
Login User
Authenticate a user with email/username and password. Email is automatically converted to lowercase. Depending on account state and 2FA, this endpoint may return: (1) full session, (2) pending 2FA partial session, or (3) EMAIL_NOT_VERIFIED when AUTH.verify_registration=true and the account is not verified.
Request Body
Responses
Login processed - returns full session or pending 2FA partial session
Logout User
Register Public User
Register a new user account publicly. Requires X-Bridge-Secret header for security. Email and user_name must be unique. Behavior depends on AUTH.verify_registration: when true, no session is created at registration and the user must verify email first; when false, the response includes sessionId and expiresAt immediately.
Authorizations
Bridge secret for backend integration
Request Body
Responses
Registration successful
Get Current User (Legacy)
Legacy current-user endpoint. Uses session cookie/X-Session-ID and supports pending 2FA sessions. Prefer /auth/user/me for login-compatible response shape.
Authorizations
Session ID for authenticated requests
Responses
User/session resolved (legacy shape)
Get Current User
Get current authenticated user/session state. This endpoint is strict and requires BOTH X-Bridge-Secret and a valid session (cookie or X-Session-ID). Returns login-compatible full session shape, or pending 2FA shape when the session is partial.
Authorizations
Session ID for authenticated requests
Bridge secret for backend integration
Responses
Current session resolved (full session or pending 2FA)
Update User Profile
Update the authenticated user's profile information. This is the recommended endpoint for updating user data. All fields are optional - only provided fields will be updated.
Authorizations
Session ID for authenticated requests
Request Body
Responses
Profile updated successfully
Upload Profile Picture
Upload or update user profile picture. Automatically deletes previous picture if exists. Supports image optimization and cloud storage.
Authorizations
Session ID for authenticated requests
Request Body
Image file (JPEG, PNG, WebP supported)
"binary"Responses
Picture uploaded successfully
Delete Profile Picture
Delete user's profile picture from cloud storage and database.
Authorizations
Session ID for authenticated requests
Responses
Picture deleted successfully
Request Password Reset
Complete Password Reset
Validate Password Reset Token
Validate a password reset token before allowing password change. This endpoint checks if the token is valid and not expired.
Request Body
Responses
Token validation result
Change Password
Change password for authenticated user. Requires current password for security. New password must be at least 8 characters.
Authorizations
Session ID for authenticated requests
Request Body
Responses
Password changed successfully
Validate Session
Validate the current session and return user information. Session can be provided via X-Session-ID header or session_id cookie. If session is pending 2FA, returns requires_2fa and available_methods.
Authorizations
Session ID for authenticated requests
Responses
Session is valid or pending 2FA
Validate Session (Bridge)
Validate a session token for bridge integration. Requires X-Bridge-Secret header. Session ID can be provided in JSON body, query parameter, or X-Session-ID header.
Authorizations
Bridge secret for backend integration
Parameters
Query Parameters
Session ID as query parameter (alternative to body)
Request Body
Responses
Session is valid - Returns user and session information
Get Current Session
Resolve the current session state from the HTTP-only session cookie. Used by the frontend after a social OAuth callback in cookie mode to determine whether the user has a full session or a pending 2FA session, without the session token ever appearing in the URL.
Typical usage: After a social login redirect with ?social_login=success and no session_id in the URL, the frontend calls this endpoint with credentials: 'include' to get the session state.
Responses
Session resolved successfully
Create Verification Token
Create a verification token for email or phone authentication. Sends a verification code via email or SMS. Requires X-Bridge-Secret header.
Authorizations
Bridge secret for backend integration
Request Body
Responses
Verification token created and sent successfully
Validate Token (GET)
Validate a verification token via query parameter and create a session. Requires X-Bridge-Secret header.
Authorizations
Bridge secret for backend integration
Parameters
Query Parameters
Verification token
"tok_abc123def456"Responses
Token validated successfully
Validate Token (POST)
Validate a verification token and create a session. Token can be provided in JSON body or query parameter. Requires X-Bridge-Secret header.
Authorizations
Bridge secret for backend integration
Parameters
Query Parameters
Token as query parameter (alternative to body)
Request Body
Responses
Token validated successfully - Returns user and session
Email Verification Link
Email verification endpoint for clicking verification links. No authentication required. Returns HTML page with verification status.
Parameters
Query Parameters
Verification token from email link
Optional redirect URL after successful verification
Responses
HTML page showing verification result
Start OAuth Flow
⚠️ BETA FEATURE - Initiate OAuth authentication flow with a social provider (Google, GitHub, Facebook, Apple, Discord, Microsoft). Redirects to provider's login page.
Parameters
Path Parameters
Social authentication provider
"google""github""facebook""apple""discord""microsoft"Responses
Redirect to OAuth provider login page
OAuth Callback Handler
⚠️ BETA FEATURE - Handle OAuth callback from social provider. This endpoint is called automatically by the OAuth provider after user authentication.
Web redirect behavior:
- Full session (no 2FA): Redirects to
{FRONTEND_URL}/login?social_login=success&provider={provider}. Session token is delivered via HTTP-only cookie — the frontend callsGET /auth/session/currentto resolve it. - 2FA required: Redirects to
{FRONTEND_URL}/login?social_login=success&requires_2fa=true&session_id={partial_session_id}&provider={provider}. The partialsession_idis always included in the URL for the 2FA case, even whencallback_mode=cookieis configured. This is necessary because Safari ITP and privacy-focused browsers block cookies set during cross-origin OAuth redirect chains, making cookie-only delivery unreliable for the 2FA step. The partial session expires in 5 minutes and still requires a valid OTP code.
Parameters
Path Parameters
"google""github""facebook""apple""discord""microsoft"Query Parameters
Authorization code from OAuth provider
Response format (json for API clients, omit for web redirect)
"json"Responses
Authentication successful (API format)
API-Based Social Login (Mobile)
⚠️ BETA FEATURE - Authenticate using social provider access token or ID token. Designed for mobile apps that handle OAuth flow client-side.
Parameters
Path Parameters
"google""github""facebook""apple""discord""microsoft"Request Body
Responses
Authentication successful
Get Available Providers
⚠️ BETA FEATURE - Get list of enabled social authentication providers and their configuration.
Responses
List of available providers
Get Linked Social Accounts
⚠️ BETA FEATURE - Get list of social accounts linked to the authenticated user.
Authorizations
Session ID for authenticated requests
Responses
List of linked social accounts
Unlink Social Account
⚠️ BETA FEATURE - Unlink a social account from the authenticated user.
Authorizations
Session ID for authenticated requests
Parameters
Path Parameters
"google""github""facebook""apple""discord""microsoft"Responses
Account unlinked successfully
Resend Verification Email
Resend verification email to a registered user. Requires X-Bridge-Secret header. For security, always returns success even if email doesn't exist.
Authorizations
Bridge secret for backend integration
Request Body
Responses
Request processed successfully (doesn't reveal if email exists)
Search and List Users
Search and list users with pagination and filtering. Requires admin or superadmin role.
Authorizations
Session ID for authenticated requests
Parameters
Query Parameters
Search query (searches in email, name, username)
Filter by user type (can be any custom user type: customer, admin, superadmin, teacher, student, etc.)
"customer"Page number
1Items per page
20Sort field
"created_at"Sort order
"asc""desc""desc"Responses
Users list retrieved successfully
Create New User
Create a new user account. Requires admin or superadmin role. Only superadmin can create superadmin users. Admin-created users are verified by default.
Authorizations
Session ID for authenticated requests
Request Body
Responses
User created successfully
Get User Details
Get detailed information about a specific user including their sessions. Requires admin or superadmin role.
Authorizations
Session ID for authenticated requests
Parameters
Path Parameters
User ID
"usr_123abc"Responses
User details retrieved successfully
Update User
Update user information. Requires admin or superadmin role. Non-superadmin cannot modify superadmin users. Only superadmin can change user types to/from superadmin.
Authorizations
Session ID for authenticated requests
Parameters
Path Parameters
User ID
Request Body
Responses
User updated successfully
Change User Password (Admin)
Change password for any user. Requires admin or superadmin role. Non-superadmin cannot change superadmin passwords. Invalidates all active sessions for the target user.
Authorizations
Session ID for authenticated requests
Request Body
Responses
Password changed successfully
2FA System Status
List User 2FA Methods
Returns active 2FA methods configured for current user.
Authorizations
Session ID for authenticated requests
Responses
User methods
Start Email 2FA Setup
Starts email verification flow and sends a code.
Authorizations
Session ID for authenticated requests
Request Body
Responses
Setup started
Start SMS 2FA Setup
Starts SMS verification flow and sends a code.
Authorizations
Session ID for authenticated requests
Request Body
Responses
Setup started
Start 2FA Challenge
Resends a verification code for pending or active sessions.
Authorizations
Session ID for authenticated requests
Parameters
Path Parameters
"email""sms"Request Body
Responses
Challenge started
Verify 2FA Code
Verifies code for login, setup, or remove action.
Authorizations
Session ID for authenticated requests
Request Body
Responses
Verification successful
Delete 2FA Method
Removes user method after re-verification.
Authorizations
Session ID for authenticated requests
Parameters
Path Parameters
Request Body
Responses
Method removed
Toggle User 2FA
Enables or disables two-factor for current account.
Authorizations
Session ID for authenticated requests
Request Body
Responses
Toggle updated
Module Hub
Operations for module discovery, status, installation, and updates
Operations
Check Hub Status
Verifies if Module Hub core registry tables are installed.
Authorizations
Session ID for authenticated requests
Responses
Hub status
Hub Install Dry Run
Run Hub Install
Discover Modules
Discovers available modules by reading manifests.
Authorizations
Session ID for authenticated requests
Responses
Available modules
Check Module Status
Returns status, drift and component-level health for one module.
Authorizations
Session ID for authenticated requests
Parameters
Path Parameters
Responses
Module status
Read Module Registry
Module Install Dry Run
Plans installation for selected module and components.
Authorizations
Session ID for authenticated requests
Parameters
Path Parameters
Request Body
Responses
Install plan generated
Run Module Install
Executes installation plan for a module.
Authorizations
Session ID for authenticated requests
Parameters
Path Parameters
Request Body
Responses
Module install executed
Module Update Dry Run
Plans update actions for outdated or drifted components.
Authorizations
Session ID for authenticated requests
Parameters
Path Parameters
Request Body
Responses
Update plan generated
Run Module Update
Applies updates to selected or all outdated components.
Authorizations
Session ID for authenticated requests
Parameters
Path Parameters
Request Body
Responses
Update executed
Blog
Operations
List Blog Posts
Lists posts with pagination, sorting and content filters.
Parameters
Query Parameters
11110010"created_at""published_at""updated_at""title""asc""desc""desc"Responses
Posts list
Create Blog Post
Creates a blog post for writer/admin roles.
Authorizations
Session ID for authenticated requests
Request Body
Responses
Post created
Get Author Profile
Get Blog Post by Slug
Get Blog Post by Id
Update Blog Post
Delete Blog Post
Publish Blog Post
Unpublish Blog Post
Schedule Blog Post
Restore Blog Post
Upload Featured Image
Delete Featured Image
List Blog Categories
Create Blog Category
Update Blog Category
Delete Blog Category
Create Blog Tag
Update Blog Tag
Delete Blog Tag
List Blog Comments
Create Blog Comment
Update Blog Comment
Delete Blog Comment
Moderate Blog Comment
Authorizations
Session ID for authenticated requests
Parameters
Path Parameters
Request Body
Responses
Moderation applied
Get Post Reactions
Add or Toggle Reaction
Bookmark Blog Post
Remove Blog Bookmark
List My Bookmarks
Track Blog View
Get Blog Stats
List Blog Translations
Create Blog Translation
Authorizations
Session ID for authenticated requests
Parameters
Path Parameters
Request Body
Responses
Translation created
Update Blog Translation
Authorizations
Session ID for authenticated requests
Parameters
Path Parameters
Request Body
Responses
Translation updated
Delete Blog Translation
Generate Blog Sitemap
📚 Additional Resources
💡 Need More Help?
- 📖 Complete API Reference - Detailed documentation with Scalar
- 🎨 Flowfull Clients - Pre-built UI components and SDKs
- 🚀 Getting Started Guide - Set up your first instance
- 💬 Discord Community - Get help from the community
🔧 Alternative Testing Tools
You can also use these popular API clients:
- Postman - Full-featured API client
- Insomnia - Simple and elegant
- Thunder Client - VS Code extension
- HTTPie - Command-line HTTP client