Authentication

FlowZen uses NextAuth.js for web authentication. For mobile/Android apps, use the Mobile Login endpoint which returns a JWT token.

Mobile Auth: Use POST /api/auth/mobile-login to get a JWT token. Include it in all subsequent requests as Authorization: Bearer <token>.

Mobile Login

POST/api/auth/mobile-login

Login with email and password. Returns a JWT token for mobile app authentication. Use this for Android/iOS apps instead of NextAuth session.

Request Body

Field	Type	Required	Description
`email`	string	Required	Registered email address
`password`	string	Required	Account password

Response (200)

{ "token": "eyJhbGciOiJIUzI1NiIs...", "user": { "id": "...", "name": "John Doe", "email": "john@example.com", "role": "employee", "avatarUrl": "...", "company": "Acme Corp", "companyColor": "#6366f1", "team": "Engineering" } }

Errors

Status	Message
`401`	Invalid email or password
`401`	This account uses social login
`403`	Please verify your email with the OTP sent during signup before logging in.

Usage in Android

// 1. Login val response = httpClient.post("/api/auth/mobile-login") { setBody(mapOf( "email" to "user@example.com", "password" to "password123" )) } val token = response.token // 2. Use token in subsequent requests httpClient.get("/api/profile") { header("Authorization", "Bearer $token") }

Register

POST/api/auth/register

Create a new user account. Sends a 6-digit OTP to the provided email for verification.

Request Body

Field	Type	Required	Description
`name`	string	Required	Full name
`email`	string	Required	Email address
`password`	string	Required	Password (min 8 chars)
`role`	string	Optional	Role (employee, project-manager, qa-tester, human-resource, finance, admin, security, it-admin, it-administration, others). Default: employee

Response (200)

{ "user": { "id": "...", "name": "John Doe", "email": "john@example.com", "role": "employee" }, "message": "OTP sent to your email." }

Errors

Status	Message
`400`	Name, email, and an 8+ character password are required
`409`	An account with this email already exists
`500`	Unable to send OTP email

Verify OTP

POST/api/auth/verify-otp

Verify email with OTP code sent during registration. Returns a JWT token for mobile app authentication.

Field	Type	Required	Description
`email`	string	Required	Email address
`otp`	string	Required	6-digit OTP code

Response (200)

{ "ok": true, "token": "eyJhbGciOiJIUzI1NiIs...", "user": { "id": "...", "name": "John Doe", "email": "john@example.com", "role": "employee", "avatarUrl": "...", "company": "Acme Corp", "companyColor": "#6366f1", "team": "Engineering" } }

Usage in Android

// 1. Register val regResponse = httpClient.post("/api/auth/register") { setBody(mapOf( "name" to "John Doe", "email" to "john@example.com", "password" to "password123" )) } // 2. Verify OTP (returns token) val verifyResponse = httpClient.post("/api/auth/verify-otp") { setBody(mapOf( "email" to "john@example.com", "otp" to "123456" )) } val token = verifyResponse.token // 3. Use token in subsequent requests httpClient.get("/api/profile") { header("Authorization", "Bearer $token") }

Forgot Password

POST/api/auth/forgot-password

Send password reset email.

Field	Type	Required	Description
`email`	string	Required	Registered email address

{ "success": true }

Check Pending Status

POST/api/auth/check-pending

Check if user has pending approval.

Field	Type	Required	Description
`email`	string	Required	Email address (query param)

{ "pending": true }

OAuth Email Verification

For users who signed up via social login (Google, GitHub, etc.) with unverified emails. These endpoints require an authenticated session or Bearer token.

POST/api/auth/oauth/send-otp

Send a 6-digit OTP to the user's email for verification. Requires authentication.

Response (200)

{ "message": "OTP sent to your email." }

Errors

Status	Message
`401`	Unauthorized
`400`	Credentials accounts already use email verification
`400`	Account is already verified

POST/api/auth/oauth/verify-otp

Verify the OTP sent to the user's email. Requires authentication.

Request Body

Field	Type	Required	Description
`otp`	string	Required	6-digit OTP code

Response (200)

{ "ok": true }

Errors

Status	Message
`401`	Invalid OTP
`410`	OTP expired. Request a new one.

Session Mode

POST/api/auth/session-mode

Set session mode for the current user.

Field	Type	Required	Description
`mode`	string	Required	Session mode

{ "success": true }

Authentication

FlowZen uses NextAuth.js for web authentication. For mobile/Android apps, use the Mobile Login endpoint which returns a JWT token.

Mobile Auth: Use POST /api/auth/mobile-login to get a JWT token. Include it in all subsequent requests as Authorization: Bearer <token>.

Mobile Login

POST/api/auth/mobile-login

Login with email and password. Returns a JWT token for mobile app authentication. Use this for Android/iOS apps instead of NextAuth session.

Request Body

Field	Type	Required	Description
`email`	string	Required	Registered email address
`password`	string	Required	Account password

Response (200)

Errors

Status	Message
`401`	Invalid email or password
`401`	This account uses social login
`403`	Please verify your email with the OTP sent during signup before logging in.

Usage in Android

Register

POST/api/auth/register

Create a new user account. Sends a 6-digit OTP to the provided email for verification.

Request Body

Field	Type	Required	Description
`name`	string	Required	Full name
`email`	string	Required	Email address
`password`	string	Required	Password (min 8 chars)
`role`	string	Optional	Role (employee, project-manager, qa-tester, human-resource, finance, admin, security, it-admin, it-administration, others). Default: employee

Response (200)

{ "user": { "id": "...", "name": "John Doe", "email": "john@example.com", "role": "employee" }, "message": "OTP sent to your email." }

Errors

Status	Message
`400`	Name, email, and an 8+ character password are required
`409`	An account with this email already exists
`500`	Unable to send OTP email

Verify OTP

POST/api/auth/verify-otp

Verify email with OTP code sent during registration. Returns a JWT token for mobile app authentication.

Field	Type	Required	Description
`email`	string	Required	Email address
`otp`	string	Required	6-digit OTP code

Response (200)

Usage in Android

Forgot Password

POST/api/auth/forgot-password

Send password reset email.

Field	Type	Required	Description
`email`	string	Required	Registered email address

{ "success": true }

Check Pending Status

POST/api/auth/check-pending

Check if user has pending approval.

Field	Type	Required	Description
`email`	string	Required	Email address (query param)

{ "pending": true }

OAuth Email Verification

For users who signed up via social login (Google, GitHub, etc.) with unverified emails. These endpoints require an authenticated session or Bearer token.

POST/api/auth/oauth/send-otp

Send a 6-digit OTP to the user's email for verification. Requires authentication.

Response (200)

{ "message": "OTP sent to your email." }

Errors

Status	Message
`401`	Unauthorized
`400`	Credentials accounts already use email verification
`400`	Account is already verified

POST/api/auth/oauth/verify-otp

Verify the OTP sent to the user's email. Requires authentication.

Request Body

Field	Type	Required	Description
`otp`	string	Required	6-digit OTP code

Response (200)

{ "ok": true }

Errors

Status	Message
`401`	Invalid OTP
`410`	OTP expired. Request a new one.

Session Mode

POST/api/auth/session-mode

Set session mode for the current user.

Field	Type	Required	Description
`mode`	string	Required	Session mode

{ "success": true }

Authentication

Mobile Login

Request Body

Response (200)

Errors

Usage in Android

Register

Request Body

Response (200)

Errors

Verify OTP

Response (200)

Usage in Android

Forgot Password

Check Pending Status

OAuth Email Verification

Response (200)

Errors

Request Body

Response (200)

Errors

Session Mode

Loading FlowZen

Authentication

Mobile Login

Request Body

Response (200)

Errors

Usage in Android

Register

Request Body

Response (200)

Errors

Verify OTP

Response (200)

Usage in Android

Forgot Password

Check Pending Status

OAuth Email Verification

Response (200)

Errors

Request Body

Response (200)

Errors

Session Mode