Users API

Manage user profiles, update information, and handle account operations.

📖 Real API Documentation

All endpoints are documented based on the actual Flowless backend code - guaranteed to match production behavior!

Base URL

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

Get User Profile

Get the authenticated user's complete profile.

Endpoint

http

GET /auth/me

Alternative endpoint:

http

GET /auth/user/me

Headers

http

X-Session-ID: ses_xyz123456

Response

json

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_1234567890",
      "email": "user@example.com",
      "name": "John",
      "last_name": "Doe",
      "user_name": "johndoe",
      "user_type": "customer",
      "picture": "https://storage.pubflow.com/users/usr_123/picture.jpg",
      "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-07T10:00:00Z"
    }
  }
}

Update User Profile

Update user profile information.

Endpoint

http

PUT /auth/profile

Alternative endpoint (with enhanced validation):

http

PUT /auth/user/me

Headers

http

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

Request Body

json

{
  "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"
}

Parameters

Field	Type	Required	Description
`name`	string	No	User's first name
`lastName`	string	No	User's last name
`userName`	string	No	Unique username
`phone`	string	No	Phone number
`dob`	string	No	Date of birth (YYYY-MM-DD)
`gender`	string	No	Gender
`referenceId`	string	No	External reference ID
`recoveryEmail`	string	No	Recovery email address
`tmz`	string	No	Timezone (e.g., "America/New_York")

Enhanced Profile Fields

The /auth/user/me endpoint supports additional fields:

email - Change email (requires permission)
two_factor - Enable/disable 2FA
mobile - Mobile number
bio - User biography
display_name - Display name
first_time - First time user flag
metadata - Custom JSON metadata

Response

json

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_1234567890",
      "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"
    }
  }
}

Upload Profile Picture

Upload or update user's profile picture.

Endpoint

http

POST /auth/upload/picture

Headers

http

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

Request Body (Form Data)

picture: [File]

Supported Formats

JPEG (.jpg, .jpeg)
PNG (.png)
WebP (.webp)
GIF (.gif)
Max size: 10MB
Automatic compression and optimization

Response

json

{
  "success": true,
  "data": {
    "picture_url": "https://storage.pubflow.com/users/usr_1234567890/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"
}

Example (JavaScript)

javascript

async function uploadProfilePicture(file: File) {
  const formData = new FormData();
  formData.append('picture', file);

  const response = await fetch(
    `${FLOWLESS_URL}/auth/upload/picture`,
    {
      method: 'POST',
      headers: {
        'X-Session-ID': sessionId,
      },
      body: formData,
    }
  );

  const data = await response.json();
  return data.data.picture_url;
}

Delete Profile Picture

Delete user's profile picture.

Endpoint

http

DELETE /auth/upload/picture

Headers

http

X-Session-ID: ses_xyz123456

Response

json

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

Change Password

Change the user's password (authenticated users).

Endpoint

http

POST /auth/password-change/self

Headers

http

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

Request Body

json

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

Response

json

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

Error Responses

json

// Incorrect current password
{
  "success": false,
  "error": "Current password is incorrect"
}

// Weak new password
{
  "success": false,
  "error": "New password must be at least 8 characters long"
}

Request Password Reset

Request a password reset email.

Endpoint

http

POST /auth/password-reset/request

Request Body

json

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

Response

json

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

Security Feature

This endpoint always returns success, even if the email doesn't exist, to prevent email enumeration attacks.

Validate Password Reset Token

Validate a password reset token before using it.

Endpoint

http

POST /auth/password-reset/validate

Request Body

json

{
  "token": "reset_token_abc123"
}

Response

json

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

Reset Password

Reset password using the token from the email.

Endpoint

http

POST /auth/password-reset/complete

Request Body

json

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

Response

json

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

Error Responses

json

// Invalid or expired token
{
  "success": false,
  "error": "Invalid or expired reset token"
}

// Weak password
{
  "success": false,
  "error": "Password must be at least 8 characters long"
}

Resend Verification Email

Resend the email verification email.

Endpoint

http

POST /auth/resend-verification

Headers

http

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

Request Body

json

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

Response

json

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

Requires Bridge Secret

This endpoint requires the X-Bridge-Secret header for security. Get your bridge secret from the Pubflow dashboard.

Admin - Search Users

Search and filter users (admin/superadmin only).

Endpoint

http

GET /auth/users

Headers

http

X-Session-ID: ses_admin_xyz

Query Parameters

Parameter	Type	Required	Description
`q`	string	No	Search query (email, name, username)
`userType`	string	No	Filter by user type
`page`	number	No	Page number (default: 1)
`limit`	number	No	Results per page (default: 10)

Example Request

http

GET /auth/users?q=john&userType=customer&page=1&limit=10

Response

json

{
  "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
    }
  }
}

Admin - Get User Details

Get detailed information about a specific user (admin/superadmin only).

Endpoint

http

GET /auth/admin/users/:id

Headers

http

X-Session-ID: ses_admin_xyz

Response

json

{
  "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
  }
}

Admin - Update User

Update any user's information (admin/superadmin only).

Endpoint

http

PUT /auth/admin/users/:id

Headers

http

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

Request Body

json

{
  "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

json

{
  "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"
  }
}

Permission Restrictions

Only superadmin can modify superadmin users
Only superadmin can change user_type to/from superadmin
Admins cannot modify users with higher privileges

Admin - Change User Password

Change any user's password (admin/superadmin only).

Endpoint

http

POST /auth/password-change/admin

Headers

http

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

Request Body

json

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

Response

json

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

Session Invalidation

All active sessions for the user will be invalidated, forcing them to log in again with the new password.

Rate Limiting

User endpoints are rate-limited for security:

Endpoint	Limit	Window
`GET /auth/me`	100 requests	1 minute
`PUT /auth/profile`	10 requests	1 minute
`POST /auth/upload/picture`	5 requests	1 hour
`POST /auth/password-change/self`	5 requests	1 hour
`POST /auth/password-reset/request`	3 requests	1 hour
`POST /auth/resend-verification`	3 requests	1 hour

Next Steps

API Playground - Test all endpoints interactively
Authentication API - Login and registration
Sessions API - Session management
Flowfull Clients - Pre-built UI components
Discord Community - Get help

Users API ​

Base URL ​

Get User Profile ​

Endpoint ​

Headers ​

Response ​

Update User Profile ​

Endpoint ​

Headers ​

Request Body ​

Parameters ​

Response ​

Upload Profile Picture ​

Endpoint ​

Headers ​

Request Body (Form Data) ​

Supported Formats ​

Response ​

Example (JavaScript) ​

Delete Profile Picture ​

Endpoint ​

Headers ​

Response ​

Change Password ​

Endpoint ​

Headers ​

Request Body ​

Response ​

Error Responses ​

Request Password Reset ​

Endpoint ​

Request Body ​

Response ​

Validate Password Reset Token ​

Endpoint ​

Request Body ​

Response ​

Reset Password ​

Endpoint ​

Request Body ​

Response ​

Error Responses ​

Resend Verification Email ​

Endpoint ​

Headers ​

Request Body ​

Response ​

Admin - Search Users ​

Endpoint ​

Headers ​

Query Parameters ​

Example Request ​

Response ​

Admin - Get User Details ​

Endpoint ​

Headers ​

Response ​

Admin - Update User ​

Endpoint ​

Headers ​

Request Body ​

Response ​

Admin - Change User Password ​

Endpoint ​

Headers ​

Request Body ​

Response ​

Rate Limiting ​

Next Steps ​

Users API

Base URL

Get User Profile

Endpoint

Headers

Response

Update User Profile

Endpoint

Headers

Request Body

Parameters

Response

Upload Profile Picture

Endpoint

Headers

Request Body (Form Data)

Supported Formats

Response

Example (JavaScript)

Delete Profile Picture

Endpoint

Headers

Response

Change Password

Endpoint

Headers

Request Body

Response

Error Responses

Request Password Reset

Endpoint

Request Body

Response

Validate Password Reset Token

Endpoint

Request Body

Response

Reset Password

Endpoint

Request Body

Response

Error Responses

Resend Verification Email

Endpoint

Headers

Request Body

Response

Admin - Search Users

Endpoint

Headers

Query Parameters

Example Request

Response

Admin - Get User Details

Endpoint

Headers

Response

Admin - Update User

Endpoint

Headers

Request Body

Response

Admin - Change User Password

Endpoint

Headers

Request Body

Response

Rate Limiting

Next Steps