🎮 API Playground

Test all Flowless authentication endpoints with real examples from the codebase.

📖 Documentation Based on Real Code

All endpoints, request/response examples, and field names are extracted directly from the Flowless backend code - guaranteed to be accurate and up-to-date!

🔧 Need a Visual API Tester?

For interactive API testing with a UI, use tools like:

• Postman - Full-featured API client
• Insomnia - Simple and elegant
• Thunder Client - VS Code extension

Or use our Flowfull Clients libraries that handle all API calls for you! 🎨

---

🔐 Core Authentication

POST /auth/register

Register a new user account (admin-only endpoint).

Authentication: Requires admin or superadmin role

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "name": "John",
  "lastName": "Doe",
  "userName": "johndoe",
  "userType": "customer"
}

Response (200 OK):

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "John",
    "lastName": "Doe",
    "userName": "johndoe",
    "userType": "customer"
  }
}

---

POST /auth/register/public

Public registration endpoint (requires bridge secret).

Headers:

X-Bridge-Secret: your_bridge_secret
Content-Type: application/json

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "name": "John",
  "lastName": "Doe",
  "userName": "johndoe"
}

Response (200 OK) - No Verification Required:

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "name": "John",
      "lastName": "Doe",
      "userName": "johndoe",
      "userType": "customer",
      "isVerified": true
    },
    "sessionId": "ses_xyz789",
    "expiresAt": "2025-12-14T10:00:00Z"
  }
}

Response (200 OK) - Verification Required:

{
  "success": true,
  "message": "Registration successful. Please check your email to verify your account.",
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "name": "John",
      "lastName": "Doe",
      "userType": "customer",
      "isVerified": false,
      "requiresVerification": true
    }
  }
}

---

POST /auth/login

Authenticate a user and create a session.

Request Body (Email):

{
  "email": "user@example.com",
  "password": "SecurePass123!"
}

Request Body (Username):

{
  "userName": "johndoe",
  "password": "SecurePass123!"
}

Response (200 OK):

{
  "success": true,
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "John",
    "last_name": "Doe",
    "user_name": "johndoe",
    "user_type": "customer",
    "picture": null,
    "phone": null,
    "is_verified": true,
    "two_factor": false,
    "created_at": "2025-12-07T10:00:00Z",
    "updated_at": "2025-12-07T10:00:00Z"
  },
  "sessionId": "ses_xyz789",
  "expiresAt": "2025-12-14T10:00:00Z"
}

Error Response (403) - Email Not Verified:

{
  "success": false,
  "error": "Please verify your email address before logging in. Check your inbox for a verification email.",
  "code": "EMAIL_NOT_VERIFIED"
}

---

POST /auth/logout

Logout and invalidate the current session.

Headers:

X-Session-ID: ses_xyz789

Response (200 OK):

{
  "success": true,
  "message": "Logged out successfully"
}

---

GET /auth/me

Get current authenticated user information.

Headers:

X-Session-ID: ses_xyz789

Response (200 OK):

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "name": "John",
      "last_name": "Doe",
      "user_name": "johndoe",
      "user_type": "customer",
      "picture": null,
      "phone": null,
      "is_verified": true,
      "two_factor": false,
      "dob": null,
      "gender": null,
      "reference_id": null,
      "recovery_email": null,
      "tmz": null,
      "created_at": "2025-12-07T10:00:00Z",
      "updated_at": "2025-12-07T10:00:00Z"
    }
  }
}

---

GET /auth/validation

Validate a session (cookie or header).

Headers (Option 1):

X-Session-ID: ses_xyz789

Cookies (Option 2):

session_id=ses_xyz789

Response (200 OK):

{
  "success": true,
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "John",
    "lastName": "Doe",
    "userName": "johndoe",
    "userType": "customer",
    "picture": null,
    "isVerified": true,
    "twoFactor": false
  }
}

---

👤 User Profile Management

PUT /auth/profile

Update user profile information.

Headers:

X-Session-ID: ses_xyz789
Content-Type: application/json

Request Body:

{
  "name": "John",
  "lastName": "Doe",
  "userName": "johndoe",
  "phone": "+1234567890",
  "dob": "1990-01-01",
  "gender": "male",
  "referenceId": "ref_123",
  "recoveryEmail": "recovery@example.com",
  "tmz": "America/New_York"
}

Response (200 OK):

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "name": "John",
      "lastName": "Doe",
      "userName": "johndoe",
      "userType": "customer",
      "picture": null,
      "phone": "+1234567890",
      "isVerified": true,
      "twoFactor": false,
      "dob": "1990-01-01",
      "gender": "male",
      "reference_id": "ref_123",
      "recovery_email": "recovery@example.com",
      "tmz": "America/New_York",
      "updatedAt": "2025-12-07T11:00:00Z"
    }
  }
}

---

GET /auth/user/me

Get current user profile (alternative endpoint).

Headers:

X-Session-ID: ses_xyz789

Response: Same as GET /auth/me

---

PUT /auth/user/me

Update current user profile (alternative endpoint with enhanced validation).

Headers:

X-Session-ID: ses_xyz789
Content-Type: application/json

Request Body:

{
  "name": "John",
  "last_name": "Doe",
  "email": "newemail@example.com",
  "user_name": "johndoe",
  "phone": "+1234567890",
  "two_factor": true,
  "mobile": "+1234567890",
  "tmz": "America/New_York",
  "bio": "Software developer",
  "dob": "1990-01-01",
  "recovery_email": "recovery@example.com",
  "display_name": "John D.",
  "gender": "male",
  "reference_id": "ref_123"
}

Response (200 OK):

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "newemail@example.com",
    "name": "John",
    "last_name": "Doe",
    "user_name": "johndoe",
    "user_type": "customer",
    "picture": null,
    "phone": "+1234567890",
    "is_verified": true,
    "two_factor": true,
    "mobile": "+1234567890",
    "tmz": "America/New_York",
    "bio": "Software developer",
    "dob": "1990-01-01",
    "recovery_email": "recovery@example.com",
    "display_name": "John D.",
    "gender": "male",
    "reference_id": "ref_123",
    "updated_at": "2025-12-07T11:00:00Z"
  }
}

---

🔒 Password Management

POST /auth/password-reset/request

Request a password reset email.

Request Body:

{
  "email": "user@example.com"
}

Response (200 OK):

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

---

POST /auth/password-reset/validate

Validate a password reset token.

Request Body:

{
  "token": "reset_token_abc123"
}

Response (200 OK):

{
  "valid": true,
  "message": "Token is valid"
}

---

POST /auth/password-reset/complete

Complete password reset with token.

Request Body:

{
  "token": "reset_token_abc123",
  "password": "NewSecurePass123!"
}

Response (200 OK):

{
  "success": true,
  "message": "Password reset successfully"
}

---

POST /auth/password-change/self

Change password (authenticated users).

Headers:

X-Session-ID: ses_xyz789
Content-Type: application/json

Request Body:

{
  "currentPassword": "OldPassword123!",
  "newPassword": "NewPassword456!"
}

Response (200 OK):

{
  "success": true,
  "message": "Password updated successfully"
}

---

POST /auth/password-change/admin

Admin password change (admin/superadmin only).

Headers:

X-Session-ID: ses_admin_xyz
Content-Type: application/json

Request Body:

{
  "userId": "usr_abc123",
  "newPassword": "NewPassword456!"
}

Response (200 OK):

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

---

📧 Email Verification

POST /auth/resend-verification

Resend email verification.

Headers:

X-Bridge-Secret: your_bridge_secret
Content-Type: application/json

Request Body:

{
  "email": "user@example.com"
}

Response (200 OK):

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

---

📸 Profile Picture

POST /auth/upload/picture

Upload profile picture.

Headers:

X-Session-ID: ses_xyz789
Content-Type: multipart/form-data

Request Body (Form Data):

picture: [File]

Response (200 OK):

{
  "success": true,
  "data": {
    "picture_url": "https://storage.pubflow.com/users/usr_abc123/picture.jpg",
    "file_size": 245678,
    "original_size": 512000,
    "compression_ratio": 0.48,
    "method": "cloud_config"
  },
  "message": "Picture uploaded successfully",
  "timestamp": "2025-12-07T11:00:00Z"
}

---

DELETE /auth/upload/picture

Delete profile picture.

Headers:

X-Session-ID: ses_xyz789

Response (200 OK):

{
  "success": true,
  "message": "Picture deleted successfully"
}

---

🔗 Bridge Validation

POST /auth/bridge/validate

Validate session for bridge integration (requires bridge secret).

Headers:

X-Bridge-Secret: your_bridge_secret
Content-Type: application/json

Request Body (Option 1 - JSON):

{
  "sessionId": "ses_xyz789"
}

Request Body (Option 2 - Query Parameter):

?sessionId=ses_xyz789

Request Body (Option 3 - Header):

X-Session-ID: ses_xyz789

Response (200 OK):

{
  "success": true,
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "John",
    "last_name": "Doe",
    "user_name": "johndoe",
    "user_type": "customer",
    "picture": null,
    "phone": null,
    "is_verified": true,
    "two_factor": false
  },
  "session": {
    "id": "ses_xyz789",
    "userId": "usr_abc123",
    "expiresAt": "2025-12-14T10:00:00Z",
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "lastUsedAt": "2025-12-07T11:00:00Z"
  },
  "expires_at": "2025-12-14T10:00:00Z",
  "timestamp": "2025-12-07T11:00:00Z"
}

---

👥 Admin - User Management

GET /auth/users

Search users (admin/superadmin only).

Headers:

X-Session-ID: ses_admin_xyz

Query Parameters:

?q=john&userType=customer&page=1&limit=10

Response (200 OK):

{
  "success": true,
  "data": {
    "users": [
      {
        "id": "usr_abc123",
        "email": "user@example.com",
        "name": "John",
        "lastName": "Doe",
        "userName": "johndoe",
        "userType": "customer",
        "isVerified": true,
        "createdAt": "2025-12-07T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "pages": 1
    }
  }
}

---

GET /auth/admin/users/:id

Get specific user details (admin/superadmin only).

Headers:

X-Session-ID: ses_admin_xyz

Response (200 OK):

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "John",
    "last_name": "Doe",
    "user_type": "customer",
    "picture": null,
    "user_name": "johndoe",
    "phone": "+1234567890",
    "is_verified": true,
    "two_factor": false,
    "created_at": "2025-12-07T10:00:00Z",
    "updated_at": "2025-12-07T11:00:00Z",
    "sessions": [
      {
        "id": "ses_xyz789",
        "sessionPrefix": "ses_xyz",
        "ipAddress": "192.168.1.1",
        "userAgent": "Mozilla/5.0...",
        "userDevice": "desktop",
        "lastUsedAt": "2025-12-07T11:00:00Z",
        "createdAt": "2025-12-07T10:00:00Z",
        "expiresAt": "2025-12-14T10:00:00Z",
        "status": "active"
      }
    ],
    "sessionCount": 1
  }
}

---

PUT /auth/admin/users/:id

Update user (admin/superadmin only).

Headers:

X-Session-ID: ses_admin_xyz
Content-Type: application/json

Request Body:

{
  "name": "John",
  "last_name": "Doe",
  "user_name": "johndoe",
  "email": "newemail@example.com",
  "phone": "+1234567890",
  "is_verified": true,
  "two_factor": false,
  "user_type": "customer",
  "dob": "1990-01-01",
  "gender": "male",
  "reference_id": "ref_123",
  "recovery_email": "recovery@example.com",
  "tmz": "America/New_York"
}

Response (200 OK):

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "newemail@example.com",
    "name": "John",
    "last_name": "Doe",
    "user_type": "customer",
    "user_name": "johndoe",
    "picture": null,
    "phone": "+1234567890",
    "is_verified": true,
    "two_factor": false,
    "dob": "1990-01-01",
    "gender": "male",
    "reference_id": "ref_123",
    "recovery_email": "recovery@example.com",
    "tmz": "America/New_York",
    "created_at": "2025-12-07T10:00:00Z",
    "updated_at": "2025-12-07T12:00:00Z"
  }
}

---

🌐 Social Authentication

GET /auth/social/:provider/login

Start OAuth flow (web-based).

Supported Providers: google, github, facebook, apple, discord, microsoft

Example:

GET /auth/social/google/login

Response: Redirects to provider's OAuth page

---

GET /auth/social/:provider/callback

Handle OAuth callback (automatic).

Query Parameters:

?code=oauth_code_abc123

Response (Web): Redirects to frontend with session cookie

Response (API - with format=json):

{
  "success": true,
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "John Doe",
    "picture": "https://example.com/avatar.jpg"
  },
  "sessionId": "ses_xyz789",
  "expiresAt": "2025-12-14T10:00:00Z",
  "loginType": "social_auth",
  "provider": "google"
}

---

POST /auth/social/:provider/login-api

API-based social login (for mobile apps).

Request Body:

{
  "accessToken": "google_access_token_abc123"
}

Or:

{
  "idToken": "google_id_token_xyz789"
}

Response (200 OK):

{
  "success": true,
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "John Doe",
    "picture": "https://example.com/avatar.jpg"
  },
  "sessionId": "ses_xyz789",
  "expiresAt": "2025-12-14T10:00:00Z",
  "loginType": "social_auth_api",
  "provider": "google"
}

---

GET /auth/social/providers

Get available social providers.

Response (200 OK):

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

---

GET /auth/social/accounts

Get user's linked social accounts.

Headers:

X-Session-ID: ses_xyz789

Response (200 OK):

{
  "success": true,
  "data": {
    "accounts": [
      {
        "provider": "google",
        "provider_email": "user@gmail.com",
        "provider_name": "John Doe",
        "provider_picture": "https://example.com/avatar.jpg",
        "linked_at": "2025-12-07T10:00:00Z",
        "last_updated": "2025-12-07T10:00:00Z"
      }
    ]
  }
}

---

DELETE /auth/social/accounts/:provider

Unlink social account.

Headers:

X-Session-ID: ses_xyz789

Response (200 OK):

{
  "success": true,
  "message": "google account unlinked successfully"
}

---

📚 Related Resources

• 🔐 Authentication API - Detailed authentication docs
• 👤 Users API - User management docs
• 🎨 Flowfull Clients - Pre-built UI components
• 💬 Discord Community - Get help and share ideas X-Session-Id: ses_xyz789

**Response (200 OK):**
```json
{
  "success": true,
  "message": "Logged out successfully"
}

---

🔄 Session Management

POST /auth/validate

Validate a session token (used by your backend).

Request Body:

{
  "session_id": "ses_xyz789",
  "bridge_secret": "your_bridge_secret"
}

Response (200 OK):

{
  "valid": true,
  "user": {
    "id": "usr_abc123",
    "email": "demo@example.com",
    "name": "Demo User"
  },
  "trust_token": "trust_abc123xyz"
}

---

POST /auth/refresh

Refresh a session to extend its lifetime.

Headers:

X-Session-Id: ses_xyz789

Response (200 OK):

{
  "success": true,
  "session_id": "ses_new456",
  "expires_at": "2025-12-14T10:00:00Z"
}

---

👤 User Management

PUT /auth/update

Update user profile information.

Headers:

X-Session-Id: ses_xyz789

Request Body:

{
  "name": "Updated Name",
  "email": "newemail@example.com"
}

Response (200 OK):

{
  "success": true,
  "user": {
    "id": "usr_abc123",
    "email": "newemail@example.com",
    "name": "Updated Name"
  }
}

---

POST /auth/change-password

Change user password.

Headers:

X-Session-Id: ses_xyz789

Request Body:

{
  "current_password": "SecurePass123!",
  "new_password": "NewSecurePass456!"
}

Response (200 OK):

{
  "success": true,
  "message": "Password changed successfully"
}

---

POST /auth/upload-picture

Upload user profile picture.

Headers:

X-Session-Id: ses_xyz789
Content-Type: multipart/form-data

Request Body:

picture: [File]

Response (200 OK):

{
  "success": true,
  "picture_url": "https://cdn.pubflow.com/users/usr_abc123/picture.jpg"
}

---

🔑 Password Recovery

POST /auth/forgot-password

Request password reset email.

Request Body:

{
  "email": "demo@example.com"
}

Response (200 OK):

{
  "success": true,
  "message": "Password reset email sent"
}

---

POST /auth/reset-password

Reset password using token from email.

Request Body:

{
  "token": "reset_token_abc123",
  "new_password": "NewSecurePass456!"
}

Response (200 OK):

{
  "success": true,
  "message": "Password reset successfully"
}

---

📧 Email Verification

POST /auth/verify-email

Verify email address using token.

Request Body:

{
  "token": "verify_token_abc123"
}

Response (200 OK):

{
  "success": true,
  "message": "Email verified successfully"
}

---

POST /auth/resend-verification

Resend verification email.

Headers:

X-Session-Id: ses_xyz789

Response (200 OK):

{
  "success": true,
  "message": "Verification email sent"
}

---

🌐 OAuth Integration

GET /auth/oauth/:provider

Initiate OAuth flow (Google, GitHub, etc.).

Parameters:

• provider: google, github, facebook, apple

Example:

GET /auth/oauth/google?redirect_uri=https://yourapp.com/callback

Response (302 Redirect): Redirects to OAuth provider login page.

---

GET /auth/oauth/callback

OAuth callback handler.

Query Parameters:

code: authorization_code_from_provider
state: state_token

Response (200 OK):

{
  "success": true,
  "session_id": "ses_oauth123",
  "user": {
    "id": "usr_abc123",
    "email": "demo@example.com",
    "name": "Demo User",
    "picture": "https://avatar.url"
  }
}

---

🚀 Try It Now

💡 Interactive API Client

For a fully interactive experience with auto-complete, request/response validation, and code generation, use our Scalar API Reference.

You can also test these endpoints using:

• cURL - Copy the examples above
• Postman - Import our Postman Collection
• Your Code - Use our Client Libraries

---

📚 Next Steps

• 📖 API Reference - Complete API documentation
• 🎨 Client Libraries - Use pre-built SDKs
• 🚀 Getting Started - Create your first instance
• 💬 Discord Community - Get help from the community