Flowless

Appearance

🎮 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

  1. Select an endpoint from the list below
  2. Fill in the required parameters
  3. Click "Try it out" to send the request
  4. View the response in real-time
v1.0.0

Flowless Authentication API​

Download OpenAPI Document

Complete authentication backend for modern applications. Flowless provides managed authentication with session management, social login, password reset, and more.

Contact​

Pubflow Support/support@pubflow.com

Servers​

https://your-instance.pubflow.comYour Flowless Instance
http://localhost:8787Local Development

Authentication​

Core authentication endpoints for login, registration, and logout

Operations​

POST/auth/loginPOST/auth/logoutPOST/auth/register/public

Login User​

POST
/auth/login

Authenticate a user with email/username and password. Returns a session token for subsequent authenticated requests. Email is automatically converted to lowercase.

Request Body​

application/json
JSON
{
"email": "user@example.com",
"password": "SecurePass123!"
}

Responses​

Login successful - Returns user data and session information

application/json
JSON
{
"success": true,
"user": {
"id": "usr_123abc",
"email": "user@example.com",
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"user_type": "customer",
"picture": "https://cdn.example.com/pic.jpg",
"phone": "+1234567890",
"is_verified": true,
"two_factor": false,
"created_at": "string",
"updated_at": "string"
},
"session_id": "ses_xyz789abc123",
"expires_at": "2025-12-15T10:00:00Z"
}

Playground​

Server
Body

Samples​

Logout User​

POST
/auth/logout

Logout and invalidate the current session

Authorizations​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Responses​

Logout successful

application/json
JSON
{
"success": true,
"message": "Logged out successfully"
}

Playground​

Server
Authorization

Samples​

Register Public User​

POST
/auth/register/public

Register a new user account publicly. Requires X-Bridge-Secret header for security. Email and user_name must be unique.

Authorizations​

BridgeSecret

Bridge secret for backend integration

TypeAPI Key (header: X-Bridge-Secret)

Request Body​

application/json
JSON
{
"email": "john@example.com",
"password": "SecurePass123!",
"name": "John",
"last_name": "Doe"
}

Responses​

Registration successful

application/json
JSON
{
"success": true,
"message": "Registration successful",
"data": {
"user": {
"id": "usr_123abc",
"email": "user@example.com",
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"user_type": "customer",
"is_verified": false
},
"session_id": "ses_xyz789",
"expires_at": "2025-12-15T10:30:00Z"
}
}

Playground​

Server
Authorization
Body

Samples​

User Profile​

User profile management and updates

Operations​

GET/auth/user/mePUT/auth/user/mePOST/auth/upload/pictureDELETE/auth/upload/picture

Get Current User​

GET
/auth/user/me

Get current authenticated user profile information. This is the recommended endpoint for retrieving user data.

Authorizations​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Responses​

User information retrieved

application/json
JSON
{
"success": true,
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"user_type": "customer",
"picture": "https://storage.pubflow.com/users/usr_abc123/picture.jpg",
"phone": "+1234567890",
"is_verified": true,
"two_factor": false,
"created_at": "2025-12-07T10:00:00Z",
"updated_at": "2025-12-07T10:00:00Z"
}
}
}

Playground​

Server
Authorization

Samples​

Update User Profile​

PUT
/auth/user/me

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​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Request Body​

application/json
JSON
{
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"phone": "+1234567890",
"dob": "1990-01-01",
"gender": "string",
"reference_id": "string",
"recovery_email": "string",
"tmz": "America/New_York"
}

Responses​

Profile updated successfully

application/json
JSON
{
"success": true,
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"user_type": "customer",
"picture": "https://storage.pubflow.com/users/usr_abc123/picture.jpg",
"phone": "+1234567890",
"is_verified": true,
"two_factor": false,
"created_at": "2025-12-07T10:00:00Z",
"updated_at": "2025-12-07T10:00:00Z"
}
}
}

Playground​

Server
Authorization
Body

Samples​

Upload Profile Picture​

POST
/auth/upload/picture

Upload or update user profile picture. Automatically deletes previous picture if exists. Supports image optimization and cloud storage.

Authorizations​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Request Body​

multipart/form-data
object

Image file (JPEG, PNG, WebP supported)

Format"binary"

Responses​

Picture uploaded successfully

application/json
JSON
{
"success": true,
"data": {
"picture_url": "https://cdn.example.com/users/usr_123/picture.jpg",
"file_size": 45678,
"original_size": 123456,
"compression_ratio": "63%",
"method": "cloud_config"
},
"message": "Picture uploaded successfully",
"timestamp": "string"
}

Playground​

Server
Authorization
Body

Samples​

Delete Profile Picture​

DELETE
/auth/upload/picture

Delete user's profile picture from cloud storage and database.

Authorizations​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Responses​

Picture deleted successfully

application/json
JSON
{
"success": true,
"message": "Picture deleted successfully"
}

Playground​

Server
Authorization

Samples​

Request Password Reset​

POST
/auth/password-reset/request

Request a password reset email

Request Body​

application/json
JSON
{
"email": "user@example.com"
}

Responses​

Password reset email sent

application/json
JSON
{
"success": true,
"message": "If your email is registered, you will receive password reset instructions."
}

Playground​

Server
Body

Samples​

Complete Password Reset​

POST
/auth/password-reset/complete

Reset password using token from email

Request Body​

application/json
JSON
{
"token": "reset_token_abc123",
"password": "NewSecurePass123!"
}

Responses​

Password reset successful

application/json
JSON
{
"success": true,
"message": "Password reset successfully"
}

Playground​

Server
Body

Samples​

Validate Password Reset Token​

POST
/auth/password-reset/validate

Validate a password reset token before allowing password change. This endpoint checks if the token is valid and not expired.

Request Body​

application/json
JSON
{
"token": "reset_abc123def456"
}

Responses​

Token validation result

application/json
JSON
{
"valid": true,
"message": "Token is valid"
}

Playground​

Server
Body

Samples​

Change Password​

POST
/auth/password-change/self

Change password for authenticated user. Requires current password for security. New password must be at least 8 characters.

Authorizations​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Request Body​

application/json
JSON
{
"current_password": "OldPass123!",
"new_password": "NewPass123!"
}

Responses​

Password changed successfully

application/json
JSON
{
"success": true,
"message": "Password updated successfully"
}

Playground​

Server
Authorization
Body

Samples​

Validate Session​

GET
/auth/validation

Validate the current session and return user information. Session can be provided via X-Session-ID header or session_id cookie.

Authorizations​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Responses​

Session is valid

application/json
JSON
{
"success": true,
"user": {
"id": "usr_123abc",
"email": "user@example.com",
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"user_type": "customer",
"picture": "string",
"is_verified": true,
"two_factor": false
}
}

Playground​

Server
Authorization

Samples​

Validate Session (Bridge)​

POST
/auth/bridge/validate

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​

BridgeSecret

Bridge secret for backend integration

TypeAPI Key (header: X-Bridge-Secret)

Parameters​

Query Parameters

session_id

Session ID as query parameter (alternative to body)

Typestring

Request Body​

application/json
JSON
{
"session_id": "ses_xyz789abc123"
}

Responses​

Session is valid - Returns user and session information

application/json
JSON
{
"success": true,
"user": {
"id": "usr_123abc",
"email": "user@example.com",
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"user_type": "customer",
"picture": "string",
"phone": "string",
"is_verified": true,
"two_factor": false
},
"session": {
"id": "ses_xyz789",
"userId": "usr_123abc",
"expiresAt": "string",
"ipAddress": "192.168.1.1",
"userAgent": "string",
"lastUsedAt": "string"
},
"expires_at": "string",
"timestamp": "string"
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​

Create Verification Token​

POST
/auth/token/login

Create a verification token for email or phone authentication. Sends a verification code via email or SMS. Requires X-Bridge-Secret header.

Authorizations​

BridgeSecret

Bridge secret for backend integration

TypeAPI Key (header: X-Bridge-Secret)

Request Body​

application/json
JSON
{
"identifier": "user@example.com",
"type": "email",
"redirect_url": "https://example.com/dashboard"
}

Responses​

Verification token created and sent successfully

application/json
JSON
{
"success": true,
"message": "Verification email sent successfully",
"token_id": "tok_abc123"
}

Playground​

Server
Authorization
Body

Samples​

Validate Token (GET)​

GET
/auth/token/validate

Validate a verification token via query parameter and create a session. Requires X-Bridge-Secret header.

Authorizations​

BridgeSecret

Bridge secret for backend integration

TypeAPI Key (header: X-Bridge-Secret)

Parameters​

Query Parameters

token*

Verification token

Typestring
Required
Example"tok_abc123def456"

Responses​

Token validated successfully

Playground​

Server
Authorization
Variables
Key
Value

Samples​

Validate Token (POST)​

POST
/auth/token/validate

Validate a verification token and create a session. Token can be provided in JSON body or query parameter. Requires X-Bridge-Secret header.

Authorizations​

BridgeSecret

Bridge secret for backend integration

TypeAPI Key (header: X-Bridge-Secret)

Parameters​

Query Parameters

token

Token as query parameter (alternative to body)

Typestring

Request Body​

application/json
JSON
{
"token": "tok_abc123def456"
}

Responses​

Token validated successfully - Returns user and session

application/json
JSON
{
"success": true,
"message": "Token validated successfully",
"user": {
"id": "usr_123abc",
"email": "user@example.com",
"name": "John",
"lastName": "Doe",
"userName": "johndoe",
"userType": "customer",
"isVerified": true
},
"sessionId": "ses_xyz789",
"expiresAt": "string"
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​

Email Verification Link​

GET
/auth/token/verify

Email verification endpoint for clicking verification links. No authentication required. Returns HTML page with verification status.

Parameters​

Query Parameters

token*

Verification token from email link

Typestring
Required
redirect

Optional redirect URL after successful verification

Typestring

Responses​

HTML page showing verification result

text/html
JSON
"<html><body><h1>Verification Successful</h1></body></html>"

Playground​

Server
Variables
Key
Value

Samples​

Start OAuth Flow​

GET
/auth/social/{provider}/login

⚠️ 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

provider*

Social authentication provider

Typestring
Required
Valid values
"google""github""facebook""apple""discord""microsoft"

Responses​

Redirect to OAuth provider login page

Playground​

Server
Variables
Key
Value

Samples​

OAuth Callback Handler​

GET
/auth/social/{provider}/callback

⚠️ BETA FEATURE - Handle OAuth callback from social provider. This endpoint is called automatically by the OAuth provider after user authentication.

Parameters​

Path Parameters

provider*
Typestring
Required
Valid values
"google""github""facebook""apple""discord""microsoft"

Query Parameters

code*

Authorization code from OAuth provider

Typestring
Required
format

Response format (json for API clients, omit for web redirect)

Typestring
Valid values
"json"

Responses​

Authentication successful (API format)

application/json
JSON
{
"success": true,
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"user_type": "customer",
"picture": "https://storage.pubflow.com/users/usr_abc123/picture.jpg",
"phone": "+1234567890",
"is_verified": true,
"two_factor": false,
"created_at": "2025-12-07T10:00:00Z",
"updated_at": "2025-12-07T10:00:00Z"
},
"sessionId": "ses_xyz789",
"expiresAt": "string",
"loginType": "social_auth",
"provider": "google"
}

Playground​

Server
Variables
Key
Value

Samples​

API-Based Social Login (Mobile)​

POST
/auth/social/{provider}/login-api

⚠️ BETA FEATURE - Authenticate using social provider access token or ID token. Designed for mobile apps that handle OAuth flow client-side.

Parameters​

Path Parameters

provider*
Typestring
Required
Valid values
"google""github""facebook""apple""discord""microsoft"

Request Body​

application/json
JSON
{
"idToken": "eyJhbGciOiJSUzI1NiIs..."
}

Responses​

Authentication successful

application/json
JSON
{
"success": true,
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"user_type": "customer",
"picture": "https://storage.pubflow.com/users/usr_abc123/picture.jpg",
"phone": "+1234567890",
"is_verified": true,
"two_factor": false,
"created_at": "2025-12-07T10:00:00Z",
"updated_at": "2025-12-07T10:00:00Z"
},
"sessionId": "ses_xyz789",
"expiresAt": "string",
"loginType": "social_auth_api",
"provider": "google"
}

Playground​

Server
Variables
Key
Value
Body

Samples​

Get Available Providers​

GET
/auth/social/providers

⚠️ BETA FEATURE - Get list of enabled social authentication providers and their configuration.

Responses​

List of available providers

application/json
JSON
{
"success": true,
"data": {
"providers": [
{
"provider": "google",
"enabled": true,
"loginUrl": "/auth/social/google/login",
"apiLoginUrl": "/auth/social/google/login-api"
}
],
"allProviders": [
],
"globallyEnabled": true
}
}

Playground​

Samples​

Get Linked Social Accounts​

GET
/auth/social/accounts

⚠️ BETA FEATURE - Get list of social accounts linked to the authenticated user.

Authorizations​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Responses​

List of linked social accounts

application/json
JSON
{
"success": true,
"data": {
"accounts": [
{
"provider": "google",
"provider_email": "user@gmail.com",
"provider_name": "John Doe",
"provider_picture": "string",
"linked_at": "string",
"last_updated": "string"
}
]
}
}

Playground​

Server
Authorization

Samples​

Unlink Social Account​

DELETE
/auth/social/accounts/{provider}

⚠️ BETA FEATURE - Unlink a social account from the authenticated user.

Authorizations​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Parameters​

Path Parameters

provider*
Typestring
Required
Valid values
"google""github""facebook""apple""discord""microsoft"

Responses​

Account unlinked successfully

application/json
JSON
{
"success": true,
"message": "google account unlinked successfully"
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​

Email Verification​

Email verification and resend operations

Operations​

POST/auth/resend-verification

Resend Verification Email​

POST
/auth/resend-verification

Resend verification email to a registered user. Requires X-Bridge-Secret header. For security, always returns success even if email doesn't exist.

Authorizations​

BridgeSecret

Bridge secret for backend integration

TypeAPI Key (header: X-Bridge-Secret)

Request Body​

application/json
JSON
{
"email": "user@example.com"
}

Responses​

Request processed successfully (doesn't reveal if email exists)

application/json
JSON
{
"success": true,
"message": "If your email is registered, you will receive a verification email.",
"verification_sent": true
}

Playground​

Server
Authorization
Body

Samples​

Search and List Users​

GET
/auth/admin/users

Search and list users with pagination and filtering. Requires admin or superadmin role.

Authorizations​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Parameters​

Query Parameters

q

Search query (searches in email, name, username)

Typestring
userType

Filter by user type (can be any custom user type: customer, admin, superadmin, teacher, student, etc.)

Typestring
Example"customer"
page

Page number

Typeinteger
Default1
limit

Items per page

Typeinteger
Default20
sortBy

Sort field

Typestring
Default"created_at"
sortOrder

Sort order

Typestring
Valid values
"asc""desc"
Default"desc"

Responses​

Users list retrieved successfully

application/json
JSON
{
"success": true,
"data": {
"users": [
{
"id": "usr_abc123",
"email": "user@example.com",
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"user_type": "customer",
"picture": "https://storage.pubflow.com/users/usr_abc123/picture.jpg",
"phone": "+1234567890",
"is_verified": true,
"two_factor": false,
"created_at": "2025-12-07T10:00:00Z",
"updated_at": "2025-12-07T10:00:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 150,
"pages": 8
}
}
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​

Create New User​

POST
/auth/admin/users

Create a new user account. Requires admin or superadmin role. Only superadmin can create superadmin users. Admin-created users are verified by default.

Authorizations​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Request Body​

application/json
JSON
{
"email": "newuser@example.com",
"password": "SecurePass123!",
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"user_type": "customer",
"phone": "+1234567890",
"is_verified": true
}

Responses​

User created successfully

application/json
JSON
{
"success": true,
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"user_type": "customer",
"picture": "https://storage.pubflow.com/users/usr_abc123/picture.jpg",
"phone": "+1234567890",
"is_verified": true,
"two_factor": false,
"created_at": "2025-12-07T10:00:00Z",
"updated_at": "2025-12-07T10:00:00Z"
}
}
}

Playground​

Server
Authorization
Body

Samples​

Get User Details​

GET
/auth/admin/users/{user_id}

Get detailed information about a specific user including their sessions. Requires admin or superadmin role.

Authorizations​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Parameters​

Path Parameters

user_id*

User ID

Typestring
Required
Example"usr_123abc"

Responses​

User details retrieved successfully

application/json
JSON
{
"success": true,
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"user_type": "customer",
"picture": "https://storage.pubflow.com/users/usr_abc123/picture.jpg",
"phone": "+1234567890",
"is_verified": true,
"two_factor": false,
"created_at": "2025-12-07T10:00:00Z",
"updated_at": "2025-12-07T10:00:00Z"
},
"sessions": [
{
"id": "string",
"sessionPrefix": "string",
"ipAddress": "string",
"userAgent": "string",
"userDevice": "string",
"lastUsedAt": "string",
"createdAt": "string",
"expiresAt": "string",
"status": "string"
}
],
"sessionCount": 3
}
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​

Update User​

PUT
/auth/admin/users/{user_id}

Update user information. Requires admin or superadmin role. Non-superadmin cannot modify superadmin users. Only superadmin can change user types to/from superadmin.

Authorizations​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Parameters​

Path Parameters

user_id*

User ID

Typestring
Required

Request Body​

application/json
JSON
{
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"email": "user@example.com",
"phone": "+1234567890",
"user_type": "customer",
"is_verified": true,
"two_factor": false
}

Responses​

User updated successfully

application/json
JSON
{
"success": true,
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"name": "John",
"last_name": "Doe",
"user_name": "johndoe",
"user_type": "customer",
"picture": "https://storage.pubflow.com/users/usr_abc123/picture.jpg",
"phone": "+1234567890",
"is_verified": true,
"two_factor": false,
"created_at": "2025-12-07T10:00:00Z",
"updated_at": "2025-12-07T10:00:00Z"
}
}
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​

Change User Password (Admin)​

POST
/auth/password-change/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​

SessionAuth

Session ID for authenticated requests

TypeAPI Key (header: X-Session-ID)

Request Body​

application/json
JSON
{
"user_id": "usr_123abc",
"new_password": "NewSecurePass123!"
}

Responses​

Password changed successfully

application/json
JSON
{
"success": true,
"message": "Password updated successfully. User will need to log in again."
}

Playground​

Server
Authorization
Body

Samples​

Powered by VitePress OpenAPI

📚 Additional Resources ​

💡 Need More Help?

🔧 Alternative Testing Tools

You can also use these popular API clients: