# Authentication API Documentation

## Overview

The Authentication API provides secure user authentication, session management, and user registration capabilities for the License Manager platform. This API handles user login, registration, password management, session management, and user context retrieval.

## Base URL

```
/api/v1/auth
```

## Authentication

All Authentication API endpoints are **public** except for protected routes like `/me`, `/sessions`, and `/logout` which require JWT Bearer tokens.

## Rate Limits

- **Login/Register**: 10 requests per minute per IP
- **Password Reset**: 5 requests per minute per IP  
- **Other endpoints**: 30 requests per minute per IP

## Common Response Format

All endpoints return responses in the following format:

```json
{
  "success": boolean,
  "data": object | null,
  "error": string | null
}
```

## Endpoints

### 1. User Login

Authenticate a user and return JWT tokens with user context.

- **URL**: `POST /api/v1/auth/login`
- **Rate Limit**: 10 requests/minute per IP

#### Request Body

```json
{
  "email": "user@example.com",
  "password": "userpassword123",
  "company_id": "optional-company-uuid"
}
```

#### Response

```json
{
  "success": true,
  "data": {
    "access_token": "jwt-access-token",
    "refresh_token": "jwt-refresh-token",
    "expires_in": 3600,
    "token_type": "Bearer",
    "user": {
      "id": "user-uuid",
      "email": "user@example.com",
      "email_verified": true,
      "created_at": "2024-01-15T10:30:00Z",
      "last_sign_in_at": "2024-01-15T10:30:00Z"
    },
    "user_context": {
      "highest_role": "company_admin",
      "companies": [
        {
          "id": "company-uuid",
          "name": "Acme Corp",
          "slug": "acme-corp",
          "role": "company_admin"
        }
      ],
      "current_company": {
        "id": "company-uuid",
        "name": "Acme Corp",
        "slug": "acme-corp",
        "role": "company_admin"
      },
      "permissions": ["read:licenses", "write:licenses", "read:users"]
    }
  }
}
```

#### Error Responses

- `400 Bad Request`: Missing email or password
- `401 Unauthorized`: Invalid credentials
- `403 Forbidden`: Account deactivated or company access denied
- `429 Too Many Requests`: Rate limit exceeded

### 2. User Registration

Register a new user account, optionally creating a new company.

- **URL**: `POST /api/v1/auth/register`
- **Rate Limit**: 10 requests/minute per IP

#### Request Body

```json
{
  "email": "newuser@example.com",
  "password": "securepassword123",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "New Company Ltd",
  "company_slug": "new-company",
  "invitation_token": "optional-invitation-token"
}
```

#### Response

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "user-uuid",
      "email": "newuser@example.com",
      "email_verified": false,
      "created_at": "2024-01-15T10:30:00Z"
    },
    "company": {
      "id": "company-uuid",
      "name": "New Company Ltd",
      "slug": "new-company",
      "role": "company_admin"
    },
    "requires_email_verification": true,
    "message": "Account created successfully. Please check your email for verification."
  }
}
```

#### Error Responses

- `400 Bad Request`: Invalid input data
- `409 Conflict`: Email already registered or company slug taken
- `429 Too Many Requests`: Rate limit exceeded

### 3. Get Current User

Retrieve current user information and context.

- **URL**: `GET /api/v1/auth/me`
- **Auth Required**: Yes (JWT Bearer Token)
- **Rate Limit**: 30 requests/minute per user

#### Headers

```
Authorization: Bearer <jwt-token>
```

#### Response

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "user-uuid",
      "email": "user@example.com",
      "email_verified": true,
      "created_at": "2024-01-15T10:30:00Z",
      "last_sign_in_at": "2024-01-15T10:30:00Z",
      "profile": {
        "first_name": "John",
        "last_name": "Doe",
        "avatar_url": "https://example.com/avatar.jpg",
        "timezone": "UTC",
        "language": "en"
      }
    },
    "user_context": {
      "highest_role": "company_admin",
      "companies": [
        {
          "id": "company-uuid",
          "name": "Acme Corp",
          "slug": "acme-corp",
          "role": "company_admin"
        }
      ],
      "current_company": {
        "id": "company-uuid",
        "name": "Acme Corp",
        "slug": "acme-corp",
        "role": "company_admin"
      },
      "permissions": ["read:licenses", "write:licenses", "read:users"]
    }
  }
}
```

### 4. Refresh Token

Refresh JWT access token using refresh token.

- **URL**: `POST /api/v1/auth/refresh`
- **Rate Limit**: 30 requests/minute per user

#### Request Body

```json
{
  "refresh_token": "jwt-refresh-token"
}
```

#### Response

```json
{
  "success": true,
  "data": {
    "access_token": "new-jwt-access-token",
    "refresh_token": "new-jwt-refresh-token",
    "expires_in": 3600,
    "token_type": "Bearer"
  }
}
```

### 5. Logout

Invalidate current session and logout user.

- **URL**: `POST /api/v1/auth/logout`
- **Auth Required**: Yes (JWT Bearer Token)
- **Rate Limit**: 30 requests/minute per user

#### Headers

```
Authorization: Bearer <jwt-token>
```

#### Response

```json
{
  "success": true,
  "data": {
    "message": "Successfully logged out"
  }
}
```

### 6. Password Reset Request

Request a password reset email.

- **URL**: `POST /api/v1/auth/password/reset`
- **Rate Limit**: 5 requests/minute per IP

#### Request Body

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

#### Response

```json
{
  "success": true,
  "data": {
    "message": "If an account with that email exists, a password reset link has been sent."
  }
}
```

### 7. Password Update

Update user password (requires current password or reset token).

- **URL**: `POST /api/v1/auth/password/update`
- **Auth Required**: Yes (JWT Bearer Token OR Password Reset Token)
- **Rate Limit**: 10 requests/minute per user

#### Request Body (with current password)

```json
{
  "current_password": "oldpassword123",
  "new_password": "newpassword456"
}
```

#### Request Body (with reset token)

```json
{
  "reset_token": "password-reset-token",
  "new_password": "newpassword456"
}
```

#### Response

```json
{
  "success": true,
  "data": {
    "message": "Password updated successfully"
  }
}
```

### 8. User Sessions

Get all active sessions for the current user.

- **URL**: `GET /api/v1/auth/sessions`
- **Auth Required**: Yes (JWT Bearer Token)
- **Rate Limit**: 30 requests/minute per user

#### Response

```json
{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": "session-uuid",
        "user_id": "user-uuid",
        "created_at": "2024-01-15T10:30:00Z",
        "expires_at": "2024-01-16T10:30:00Z",
        "ip_address": "192.168.1.1",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
        "is_current": true,
        "last_accessed_at": "2024-01-15T11:45:00Z"
      }
    ],
    "total": 1
  }
}
```

## Data Models

### User Object

```typescript
interface User {
  id: string;                    // UUID
  email: string;                 // User email
  email_verified: boolean;       // Email verification status
  created_at: string;           // ISO 8601 timestamp
  last_sign_in_at?: string;     // ISO 8601 timestamp
  profile?: {
    first_name?: string;
    last_name?: string;
    avatar_url?: string;
    timezone?: string;
    language?: string;
  };
}
```

### User Context Object

```typescript
interface UserContext {
  highest_role: string;         // Highest role across all companies
  companies: Company[];         // List of companies user belongs to
  current_company?: Company;    // Currently selected company
  permissions: string[];        // List of permission strings
}
```

### Company Object

```typescript
interface Company {
  id: string;                   // UUID
  name: string;                 // Company name
  slug: string;                 // URL-friendly company identifier
  role: string;                 // User's role in this company
}
```

### Session Object

```typescript
interface Session {
  id: string;                   // UUID
  user_id: string;             // User UUID
  created_at: string;          // ISO 8601 timestamp
  expires_at: string;          // ISO 8601 timestamp
  ip_address: string;          // Client IP address
  user_agent: string;          // Client user agent
  is_current: boolean;         // Whether this is the current session
  last_accessed_at: string;    // ISO 8601 timestamp
}
```

## Error Codes

### Authentication Errors

- `AUTH_001`: Invalid credentials
- `AUTH_002`: Account not found
- `AUTH_003`: Account deactivated
- `AUTH_004`: Email not verified
- `AUTH_005`: Invalid or expired token
- `AUTH_006`: Session expired
- `AUTH_007`: Insufficient permissions

### Registration Errors

- `REG_001`: Email already registered
- `REG_002`: Invalid email format
- `REG_003`: Password too weak
- `REG_004`: Company slug unavailable
- `REG_005`: Invalid invitation token

### Password Errors

- `PWD_001`: Current password incorrect
- `PWD_002`: New password too weak
- `PWD_003`: Reset token expired
- `PWD_004`: Password reset not requested

## Security Considerations

### JWT Tokens

- **Access Token**: Valid for 1 hour
- **Refresh Token**: Valid for 30 days
- **Algorithm**: RS256 with rotating keys
- **Claims**: Include user ID, roles, and permissions

### Password Requirements

- Minimum 8 characters
- Must contain at least one uppercase letter
- Must contain at least one lowercase letter
- Must contain at least one number
- Special characters recommended

### Rate Limiting

Rate limits are enforced per IP address and reset every minute:

- Login/Register: 10 requests/minute
- Password Reset: 5 requests/minute
- Other endpoints: 30 requests/minute

### Session Management

- Sessions are automatically extended on activity
- Maximum concurrent sessions: 5 per user
- Sessions expire after 24 hours of inactivity

## Code Examples

### JavaScript/Node.js

```javascript
// Login
const loginResponse = await fetch('/api/v1/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
});

const loginData = await loginResponse.json();

if (loginData.success) {
  const { access_token, refresh_token } = loginData.data;
  localStorage.setItem('access_token', access_token);
  localStorage.setItem('refresh_token', refresh_token);
}

// Get current user
const userResponse = await fetch('/api/v1/auth/me', {
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('access_token')}`
  }
});

const userData = await userResponse.json();
```

### Python

```python
import requests

# Login
login_response = requests.post('https://your-domain.com/api/v1/auth/login', 
    json={
        'email': 'user@example.com',
        'password': 'password123'
    }
)

login_data = login_response.json()

if login_data['success']:
    access_token = login_data['data']['access_token']
    
    # Get current user
    user_response = requests.get('https://your-domain.com/api/v1/auth/me',
        headers={'Authorization': f'Bearer {access_token}'}
    )
    
    user_data = user_response.json()
```

### cURL

```bash
# Login
curl -X POST https://your-domain.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

# Get current user (replace TOKEN with actual token)
curl -X GET https://your-domain.com/api/v1/auth/me \
  -H "Authorization: Bearer TOKEN"

# Password reset
curl -X POST https://your-domain.com/api/v1/auth/password/reset \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'
```

## Testing

### Postman Collection

Download our comprehensive Postman collection to test all Authentication API endpoints:

- [Authentication API Postman Collection](../public/api-docs/auth-postman-collection.json)

### Test Accounts

For testing purposes, you can use these pre-configured test accounts:

```
Email: test@example.com
Password: TestPassword123!
Role: company_admin

Email: user@test.com  
Password: UserPassword123!
Role: end_user
```

## Support

For questions about the Authentication API:

- **Email**: [support@bitcrate.co.uk](mailto:support@bitcrate.co.uk)
- **Documentation**: [https://docs.bitcrate.co.uk](https://docs.bitcrate.co.uk)
- **API Status**: [https://status.bitcrate.co.uk](https://status.bitcrate.co.uk)

## Changelog

### Version 1.0.0
- Initial release of Authentication API
- JWT-based authentication
- Session management
- Password reset functionality
- Multi-company user support 

📄 Authentication API Documentation