FR-01 — IAM API Endpoints

Introduction

This section defines the API contract for SalesFam Authentication, Identity & Access Management. It covers the interfaces required to establish user identity, verify accounts, complete onboarding, authenticate users, manage sessions, recover credentials, and enforce account access.

API Boundary

All IAM endpoints are exposed under /api/v1/auth. The endpoints documented in this section correspond directly to the functional scope defined in FR-01 — Authentication, Identity & Access Management.

Standard API Contract

All IAM endpoints use the platform-wide response conventions for successful operations, validation failures, authentication failures, authorization failures, resource and state errors, and unexpected server errors. The standard response format is defined below and applies consistently across all SalesFam functional areas.

1. API Base Convention

Use a versioned API: /api/v1. IAM endpoints live under /api/v1/auth/*.

2. Standard API Response

We should establish one response structure for the entire SalesFam backend, not create a different format for each FR.

Success:

{
  "success": true,
  "message": "Operation completed successfully.",
  "data": {}
}

When there is no useful returned data:

{
  "success": true,
  "message": "Operation completed successfully.",
  "data": null
}

Error:

{
  "success": false,
  "message": "Request could not be processed.",
  "error": {
    "code": "ERROR_CODE",
    "details": null
  }
}

Example:

{
  "success": false,
  "message": "Email is already registered.",
  "error": {
    "code": "EMAIL_ALREADY_EXISTS",
    "details": null
  }
}

For validation errors:

{
  "success": false,
  "message": "Validation failed.",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": { "email": "Invalid email format." }
  }
}

This structure should later be reused by FR-02 through FR-07.

3. Account Registration

POST /api/v1/auth/register

Purpose: Create the initial User identity and start email verification. Authentication: Not required.

Request:

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

Success — 201 Created:

{
  "success": true,
  "message": "Registration successful. Verification code sent.",
  "data": {
    "userId": "user-uuid",
    "email": "user@example.com",
    "accountStatus": "PENDING_VERIFICATION"
  }
}

Important behavior: this endpoint does not assign Company or Rep yet.

Flow: Register → User created → Verification code sent → PENDING_VERIFICATION.

4. Verify Account

POST /api/v1/auth/verify

Purpose: Verify the user's email using the verification code. Authentication: Not required.

Request:

{
  "userId": "user-uuid",
  "code": "483921"
}

userId may also be the user's email address.

Success — 200 OK:

{
  "success": true,
  "message": "Email verified successfully.",
  "data": {
    "userId": "user-uuid",
    "emailVerified": true,
    "nextStep": "ACCOUNT_TYPE_SELECTION"
  }
}

Error example:

{
  "success": false,
  "message": "Verification code is invalid or expired.",
  "error": { "code": "INVALID_VERIFICATION_CODE", "details": null }
}

5. Resend Verification Code

POST /api/v1/auth/verify/resend

Purpose: Send a new verification code. Authentication: Not required.

Request:

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

Success:

{
  "success": true,
  "message": "A new verification code has been sent.",
  "data": null
}

6. Select Account Type

POST /api/v1/auth/onboarding/account-type

Purpose: Let a verified user choose the type of account they want to create. Authentication: Required.

Request:

{ "accountType": "COMPANY" }

or:

{ "accountType": "REP" }

Success:

{
  "success": true,
  "message": "Account type selected successfully.",
  "data": { "accountType": "COMPANY", "onboardingStatus": "IN_PROGRESS" }
}

Rules:

• User must have a verified email.
• accountType must be COMPANY or REP.
• User cannot select ADMIN through normal onboarding.
• The selected type determines the onboarding path.

7. Company Onboarding

POST /api/v1/auth/onboarding/company

Purpose: Create/complete the Company profile after selecting Company. Authentication: Required.

The exact Company fields will be finalized under FR-02. For now, the endpoint contract is conceptually:

Request:

{
  "companyName": "ABC Company",
  "taxId": "123456789",
  "phone": "+251911111111",
  "address": "Addis Ababa"
}

Success:

{
  "success": true,
  "message": "Company onboarding completed.",
  "data": {
    "companyId": "company-uuid",
    "onboardingStatus": "COMPLETED",
    "accountType": "COMPANY"
  }
}

8. Sales Representative Onboarding

POST /api/v1/auth/onboarding/rep

Purpose: Create/complete the Sales Representative profile after selecting Rep. The exact Rep fields will be finalized under FR-03.

Request:

{
  "phone": "+251911111111",
  "address": "Addis Ababa"
}

Success:

{
  "success": true,
  "message": "Sales Representative onboarding completed.",
  "data": {
    "repId": "rep-uuid",
    "onboardingStatus": "COMPLETED",
    "accountType": "REP"
  }
}

9. Login

POST /api/v1/auth/login

Purpose: Authenticate an existing user. Authentication: Not required.

Request:

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

Success:

{
  "success": true,
  "message": "Login successful.",
  "data": {
    "user": {
      "id": "user-uuid",
      "email": "user@example.com",
      "role": "REP",
      "accountStatus": "ACTIVE"
    },
    "accessToken": "access-token"
  }
}

The exact token delivery mechanism will be finalized in the Security design.

10. Logout

POST /api/v1/auth/logout

Purpose: End the authenticated session. Authentication: Required.

Success:

{
  "success": true,
  "message": "Logout successful.",
  "data": null
}

The applicable session/refresh credential is revoked or invalidated according to the security design.

11. Refresh Session

POST /api/v1/auth/refresh

Purpose: Obtain a new access token/session using a valid refresh mechanism. Authentication: Refresh credential required.

Request: the refresh credential may be supplied according to the final security architecture. Conceptually:

{ "refreshToken": "refresh-token" }

Success:

{
  "success": true,
  "message": "Session refreshed successfully.",
  "data": { "accessToken": "new-access-token" }
}

12. Forgot Password

POST /api/v1/auth/forgot-password

Purpose: Start password recovery. Authentication: Not required.

Request:

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

Success: for security, we should return a generic result rather than revealing whether the email exists.

{
  "success": true,
  "message": "If the account exists, password recovery instructions have been sent.",
  "data": null
}

13. Reset Password

POST /api/v1/auth/reset-password

Purpose: Set a new password using a valid reset mechanism. Authentication: Not required.

Request:

{
  "token": "reset-token",
  "newPassword": "NewPassword123!"
}

Success:

{
  "success": true,
  "message": "Password reset successfully.",
  "data": null
}

14. IAM Endpoint Summary

Method	Endpoint	Auth	Purpose
POST	/auth/register	No	Create User
POST	/auth/verify	No	Verify email
POST	/auth/verify/resend	No	Resend code
POST	/auth/onboarding/account-type	Yes	Select Company/Rep
POST	/auth/onboarding/company	Yes	Company onboarding
POST	/auth/onboarding/rep	Yes	Rep onboarding
POST	/auth/login	No	Authenticate
POST	/auth/logout	Yes	End session
POST	/auth/refresh	Refresh credential	Refresh session
POST	/auth/forgot-password	No	Start recovery
POST	/auth/reset-password	No	Set new password

FR-01 API Flow