Authentication API

Complete reference for all authentication endpoints in Flowless.

---

Base URL

All API requests should be made to your Flowless instance:

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

---

Register User

Create a new user account with email and password.

Endpoint

POST /auth/register

Request Body

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "name": "John",
  "last_name": "Doe",
  "username": "johndoe",
  "phone": "+1234567890"
}

Parameters

Field	Type	Required	Description
email	string	Yes	User's email address (lowercase)
password	string	Yes	Password (min 8 chars)
name	string	Yes	User's first name
last_name	string	No	User's last name
username	string	No	Unique username
phone	string	No	Phone number

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_1234567890",
      "email": "user@example.com",
      "name": "John",
      "last_name": "Doe",
      "username": "johndoe",
      "phone": "+1234567890",
      "is_verified": false,
      "created_at": "2025-12-07T10:00:00Z"
    },
    "session": {
      "session_id": "ses_abcdefghijk",
      "expires_at": "2025-12-14T10:00:00Z"
    }
  }
}

Error Responses

// Email already exists
{
  "success": false,
  "error": "Email already registered"
}

// Invalid email format
{
  "success": false,
  "error": "Invalid email format"
}

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

Example

const response = await fetch('https://your-instance.pubflow.com/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'SecurePassword123!',
    name: 'John',
    last_name: 'Doe',
  }),
});

const data = await response.json();
console.log(data.data.session.session_id);

---

Login

Authenticate a user with email/username and password.

Endpoint

POST /auth/login

Request Body

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "device_id": "device_abc123"
}

Parameters

Field	Type	Required	Description
email	string	Yes*	User's email (or username)
username	string	Yes*	User's username (or email)
password	string	Yes	User's password
device_id	string	No	Device identifier for binding

*Either email or username is required

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_1234567890",
      "email": "user@example.com",
      "name": "John",
      "last_name": "Doe",
      "is_verified": true
    },
    "session": {
      "session_id": "ses_xyz123456",
      "expires_at": "2025-12-14T10:00:00Z"
    }
  }
}

Error Responses

// Invalid credentials
{
  "success": false,
  "error": "Invalid email or password"
}

// Account banned
{
  "success": false,
  "error": "Account has been banned"
}

// Email not verified (if required)
{
  "success": false,
  "error": "Please verify your email before logging in"
}

---

Get Current User

Get the authenticated user's information.

Endpoint

GET /auth/me

Headers

X-Session-ID: ses_xyz123456

Response

{
  "success": true,
  "data": {
    "id": "usr_1234567890",
    "email": "user@example.com",
    "name": "John",
    "last_name": "Doe",
    "username": "johndoe",
    "phone": "+1234567890",
    "picture": "https://example.com/avatar.jpg",
    "is_verified": true,
    "created_at": "2025-12-07T10:00:00Z"
  }
}

---

Logout

Invalidate the current session.

Endpoint

POST /auth/logout

Headers

X-Session-ID: ses_xyz123456

Response

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

---

Refresh Session

Extend the current session's expiration time.

Endpoint

POST /auth/refresh

Headers

X-Session-ID: ses_xyz123456

Response

{
  "success": true,
  "data": {
    "session_id": "ses_xyz123456",
    "expires_at": "2025-12-21T10:00:00Z"
  }
}

---

Rate Limiting

Authentication endpoints are rate-limited to prevent abuse:

Endpoint	Limit	Window
/auth/register	3 requests	1 hour
/auth/login	5 requests	15 minutes
/auth/me	100 requests	1 minute
/auth/logout	10 requests	1 minute
/auth/refresh	20 requests	1 minute

Rate Limit Headers

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

---

Next Steps

• Token Authentication - API token-based auth
• Social Authentication - OAuth login
• Sessions API - Session management
• Users API - User profile management