> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Falasefemi2/companyflow/llms.txt
> Use this file to discover all available pages before exploring further.

# Login

> Authenticate user and return JWT token

## Overview

The login endpoint authenticates employees using their email and password credentials. Upon successful authentication, it returns a JWT token valid for 24 hours along with employee and company information.

## Authentication Flow

1. Employee submits email and password
2. System validates credentials against the database
3. Checks if employee status is "active"
4. Verifies password hash using bcrypt
5. Generates JWT token with 24-hour expiration
6. Returns token with employee and company details

## Request

<ParamField body="email" type="string" required>
  Employee email address. Must be a valid email format.

  Example: `john.doe@company.com`
</ParamField>

<ParamField body="password" type="string" required>
  Employee password. Minimum 8 characters required.

  Example: `SecurePass123!`
</ParamField>

### Request Example

```json theme={null}
{
  "email": "john.doe@company.com",
  "password": "SecurePass123!"
}
```

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  Contains the authentication response data

  <ResponseField name="data.token" type="string">
    JWT authentication token valid for 24 hours. Use this token in the Authorization header for subsequent API requests.
  </ResponseField>

  <ResponseField name="data.role" type="string">
    Employee's role name (e.g., "admin", "manager", "employee")
  </ResponseField>

  <ResponseField name="data.employee" type="object">
    Employee details

    <ResponseField name="data.employee.id" type="string">
      Employee UUID
    </ResponseField>

    <ResponseField name="data.employee.company_id" type="string">
      Company UUID
    </ResponseField>

    <ResponseField name="data.employee.email" type="string">
      Employee email address
    </ResponseField>

    <ResponseField name="data.employee.phone" type="string">
      Employee phone number
    </ResponseField>

    <ResponseField name="data.employee.first_name" type="string">
      Employee first name
    </ResponseField>

    <ResponseField name="data.employee.last_name" type="string">
      Employee last name
    </ResponseField>

    <ResponseField name="data.employee.employee_code" type="string">
      Internal employee code (e.g., "EMP001")
    </ResponseField>

    <ResponseField name="data.employee.department_id" type="string">
      Department UUID
    </ResponseField>

    <ResponseField name="data.employee.designation_id" type="string">
      Designation UUID
    </ResponseField>

    <ResponseField name="data.employee.level_id" type="string">
      Level UUID
    </ResponseField>

    <ResponseField name="data.employee.manager_id" type="string">
      Manager's employee UUID (if applicable)
    </ResponseField>

    <ResponseField name="data.employee.role_id" type="string">
      Role UUID
    </ResponseField>

    <ResponseField name="data.employee.status" type="string">
      Employee status: `active`, `inactive`, `on_leave`, `terminated`, or `probation`
    </ResponseField>

    <ResponseField name="data.employee.employment_type" type="string">
      Employment type: `full_time`, `part_time`, `contract`, or `intern`
    </ResponseField>

    <ResponseField name="data.employee.date_of_birth" type="string" nullable>
      Date of birth in ISO 8601 format
    </ResponseField>

    <ResponseField name="data.employee.hire_date" type="string">
      Hire date in ISO 8601 format
    </ResponseField>

    <ResponseField name="data.employee.termination_date" type="string" nullable>
      Termination date in ISO 8601 format (if applicable)
    </ResponseField>

    <ResponseField name="data.employee.gender" type="string">
      Employee gender
    </ResponseField>

    <ResponseField name="data.employee.address" type="string">
      Employee address
    </ResponseField>

    <ResponseField name="data.employee.emergency_contact_name" type="string">
      Emergency contact name
    </ResponseField>

    <ResponseField name="data.employee.emergency_contact_phone" type="string">
      Emergency contact phone number
    </ResponseField>

    <ResponseField name="data.employee.profile_image_url" type="string">
      Profile image URL
    </ResponseField>

    <ResponseField name="data.employee.last_login_at" type="string" nullable>
      Last login timestamp in ISO 8601 format
    </ResponseField>

    <ResponseField name="data.employee.created_at" type="string">
      Account creation timestamp in ISO 8601 format
    </ResponseField>

    <ResponseField name="data.employee.updated_at" type="string">
      Last update timestamp in ISO 8601 format
    </ResponseField>
  </ResponseField>

  <ResponseField name="data.company" type="object">
    Company details

    <ResponseField name="data.company.id" type="string">
      Company UUID
    </ResponseField>

    <ResponseField name="data.company.name" type="string">
      Company name
    </ResponseField>

    <ResponseField name="data.company.slug" type="string">
      Company slug (URL-friendly identifier)
    </ResponseField>

    <ResponseField name="data.company.industry" type="string">
      Company industry
    </ResponseField>

    <ResponseField name="data.company.country" type="string">
      Company country
    </ResponseField>

    <ResponseField name="data.company.timezone" type="string">
      Company timezone
    </ResponseField>

    <ResponseField name="data.company.currency" type="string">
      Company currency code
    </ResponseField>

    <ResponseField name="data.company.registration_number" type="string">
      Company registration number
    </ResponseField>

    <ResponseField name="data.company.tax_id" type="string">
      Company tax ID
    </ResponseField>

    <ResponseField name="data.company.address" type="string">
      Company address
    </ResponseField>

    <ResponseField name="data.company.phone" type="string">
      Company phone number
    </ResponseField>

    <ResponseField name="data.company.logo_url" type="string">
      Company logo URL
    </ResponseField>

    <ResponseField name="data.company.status" type="string">
      Company status: `active`, `suspended`, or `inactive`
    </ResponseField>

    <ResponseField name="data.company.settings" type="object">
      Company-specific settings (JSON blob)
    </ResponseField>

    <ResponseField name="data.company.created_at" type="string">
      Company creation timestamp in ISO 8601 format
    </ResponseField>

    <ResponseField name="data.company.updated_at" type="string">
      Last update timestamp in ISO 8601 format
    </ResponseField>
  </ResponseField>
</ResponseField>

### Success Response Example

```json theme={null}
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "role": "admin",
    "employee": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "company_id": "987fcdeb-51a2-43f7-9876-543210fedcba",
      "email": "john.doe@company.com",
      "phone": "+1234567890",
      "first_name": "John",
      "last_name": "Doe",
      "employee_code": "EMP001",
      "department_id": "456e7890-e12b-34d5-a678-901234567890",
      "designation_id": "789f0123-e45c-67d8-a901-234567890123",
      "level_id": "012g3456-e78d-90e1-a234-567890123456",
      "manager_id": "345h6789-e01e-23f4-a567-890123456789",
      "role_id": "678i9012-e34f-56g7-a890-123456789012",
      "status": "active",
      "employment_type": "full_time",
      "date_of_birth": "1990-05-15T00:00:00Z",
      "hire_date": "2023-01-15T00:00:00Z",
      "termination_date": null,
      "gender": "male",
      "address": "123 Main St, City, Country",
      "emergency_contact_name": "Jane Doe",
      "emergency_contact_phone": "+0987654321",
      "profile_image_url": "https://example.com/avatar.jpg",
      "last_login_at": "2024-03-01T10:30:00Z",
      "created_at": "2023-01-15T09:00:00Z",
      "updated_at": "2024-03-01T10:30:00Z"
    },
    "company": {
      "id": "987fcdeb-51a2-43f7-9876-543210fedcba",
      "name": "Acme Corporation",
      "slug": "acme-corp",
      "industry": "Technology",
      "country": "United States",
      "timezone": "America/New_York",
      "currency": "USD",
      "registration_number": "REG123456",
      "tax_id": "TAX789012",
      "address": "456 Corporate Blvd, City, State",
      "phone": "+1555123456",
      "logo_url": "https://example.com/logo.png",
      "status": "active",
      "settings": {},
      "created_at": "2022-01-01T00:00:00Z",
      "updated_at": "2024-02-15T14:20:00Z"
    }
  }
}
```

## Error Responses

### 400 Bad Request

Returned when the request body is malformed or missing required fields.

```json theme={null}
{
  "success": false,
  "error": "invalid request body"
}
```

**Common causes:**

* Missing `email` or `password` field
* Invalid JSON format
* Email not in valid format

### 401 Unauthorized

Returned when the credentials are invalid or the employee account is not active.

```json theme={null}
{
  "success": false,
  "error": "invalid credentials"
}
```

**Common causes:**

* Incorrect email or password
* Employee not found in database
* Employee status is not "active" (e.g., inactive, terminated, on\_leave, probation)
* Password hash verification failed

### 500 Internal Server Error

Returned when an unexpected server error occurs.

```json theme={null}
{
  "success": false,
  "error": "internal server error message"
}
```

**Common causes:**

* Database connection failure
* JWT token generation failure
* Missing JWT\_SECRET environment variable

## JWT Token Details

The returned JWT token contains the following claims:

* `employee_id`: Employee UUID
* `role`: Employee role name
* `company_id`: Company UUID
* `email`: Employee email
* `first_name`: Employee first name
* `last_name`: Employee last name
* `sub`: Subject (employee ID)
* `iat`: Issued at timestamp
* `exp`: Expiration timestamp (24 hours from issuance)

The token is signed using HS256 algorithm with the JWT\_SECRET environment variable.

## Usage Example

### cURL

```bash theme={null}
curl -X POST https://api.companyflow.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@company.com",
    "password": "SecurePass123!"
  }'
```

### JavaScript (fetch)

```javascript theme={null}
const response = await fetch('https://api.companyflow.com/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'john.doe@company.com',
    password: 'SecurePass123!',
  }),
});

const data = await response.json();

if (data.success) {
  // Store the token for subsequent requests
  const token = data.data.token;
  localStorage.setItem('authToken', token);
  
  console.log('Login successful:', data.data.employee);
} else {
  console.error('Login failed:', data.error);
}
```

### Python (requests)

```python theme={null}
import requests

url = 'https://api.companyflow.com/auth/login'
payload = {
    'email': 'john.doe@company.com',
    'password': 'SecurePass123!'
}

response = requests.post(url, json=payload)
data = response.json()

if data['success']:
    token = data['data']['token']
    print(f"Login successful. Token: {token}")
else:
    print(f"Login failed: {data['error']}")
```

## Using the Token

After successful login, include the JWT token in the Authorization header for subsequent API requests:

```bash theme={null}
curl -X GET https://api.companyflow.com/api/employees \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

## Security Notes

* Passwords are hashed using bcrypt with default cost factor
* JWT tokens expire after 24 hours
* Only employees with "active" status can login
* Failed login attempts do not reveal whether the email exists
* Tokens should be stored securely (e.g., httpOnly cookies or secure storage)
* Always use HTTPS in production to protect credentials in transit