Authentication

Overview

The eFICA Authentication API provides secure user authentication and session management. This guide covers all authentication endpoints available to external developers and partners.

Base URLs

• Sandbox: https://sandboxapi.efica.co.za
• Production: https://loginapi.efica.co.za

Authentication Flow

1. User Login

2. Token Refresh

3. Password Reset

Endpoints

1. User Login

Endpoint: POST /auth/login

Description: Authenticate user and receive access tokens

Request:

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

Response (200 OK):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "userID": 123,
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "isAdmin": false,
    "isSuper": false,
    "partnerGUID": "123e4567-e89b-12d3-a456-426614174000",
    "companyName": "Example Corp",
    "isCharterCompany": false,
    "charterFXAssist": false,
    "allowBulkImport": true
  }
}

Error Responses:

• 400 Bad Request: Invalid input format
• 403 Forbidden: Invalid credentials or account issues

2. Token Refresh

Endpoint: POST /auth/refresh

Description: Get new access token using refresh token

Request:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200 OK):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Error Responses:

• 400 Bad Request: Invalid token format
• 403 Forbidden: Invalid or expired refresh token

3. Password Reset Request

Endpoint: POST /auth/forgot-password

Description: Send password reset email to user

Request:

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

Response (200 OK):

true

Error Responses:

• 400 Bad Request: Invalid email format
• 404 Not Found: User not found

4. Password Reset

Endpoint: POST /auth/reset-password

Description: Complete password reset with token

Request:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "password": "newpassword123"
}

Response (200 OK):

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

Error Responses:

• 400 Bad Request: Invalid token or password format
• 403 Forbidden: Invalid or expired reset token

5. User Logout

Endpoint: POST /auth/logout

Description: Invalidate user session

Headers:

Authorization: Bearer <refresh_token>

Response (201 Created):

// No response body

Error Responses:

• 400 Bad Request: Missing refresh token
• 403 Forbidden: Invalid refresh token

Standard Error Response

{
  "statusCode": 400,
  "message": "Bad Request",
  "error": "Invalid input data",
  "timestamp": "2023-01-01T00:00:00.000Z",
  "path": "/auth/login"
}

Validation Error Response

{
  "statusCode": 400,
  "message": "Bad Request",
  "errors": [
    {
      "field": "email",
      "message": "email must be an email",
      "value": "invalid-email"
    }
  ]
}

Common Error Codes

Code	Description	Action
400	Bad Request	Check request format and validation
401	Unauthorized	Provide valid authentication token
403	Forbidden	Check user permissions and account status
404	Not Found	Verify resource exists
429	Too Many Requests	Implement rate limiting
500	Internal Server Error	Contact support

Best Practices

1. Token Management

• Store tokens securely (httpOnly cookies preferred)
• Implement automatic token refresh
• Handle token expiration gracefully
• Clear tokens on logout

2. Security Considerations

• Always use HTTPS in production
• Validate all user inputs
• Implement proper error handling
• Use appropriate timeouts

3. User Experience

• Provide clear error messages
• Implement loading states
• Handle network failures gracefully
• Cache user information appropriately

Support

For authentication-related issues:

1. Check your credentials and account status
2. Verify the API URL is correct
3. Contact support at melissa@efica.co.za

---

Last Updated: 14 August 2025