# End User API Documentation

## Overview

The End User API provides endpoints for end users to manage their profile, view their licenses, and access license information within their scope. This API is designed for license holders to interact with their own data and licenses.

**Base URL:** `https://yourdomain.com/api/v1/user`

**Version:** 1.0  
**Authentication:** JWT Bearer Token  
**Rate Limit:** 50 requests per minute  
**Response Format:** JSON

## Table of Contents

1. [Authentication](#authentication)
2. [Rate Limits](#rate-limits)
3. [Error Handling](#error-handling)
4. [API Endpoints](#api-endpoints)
   - [Profile Management](#profile-management)
   - [License Management](#license-management)
5. [Data Models](#data-models)
6. [Code Examples](#code-examples)
7. [SDKs & Tools](#sdks--tools)

## Authentication

End User API requires JWT authentication obtained from the auth/login endpoint:

### 1. Obtain JWT Token
```http
POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@company.com",
  "password": "your_password"
}
```

### 2. Include Token in Headers
```http
Authorization: Bearer <jwt_token>
Content-Type: application/json
```

### 3. Required Permissions
- User must be authenticated
- Can only access their own data
- No administrative privileges required

## Rate Limits

API calls are rate limited per user:
- **Profile endpoints:** 50 requests per minute
- **License endpoints:** 50 requests per minute

Rate limit headers:
- `X-RateLimit-Limit`: Maximum requests allowed
- `X-RateLimit-Remaining`: Remaining requests
- `X-RateLimit-Reset`: Reset timestamp

## Error Handling

All APIs return consistent error responses:

```json
{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "validation error details"
  }
}
```

**Common HTTP Status Codes:**
- `200` - Success
- `201` - Created
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `429` - Rate Limited
- `500` - Internal Server Error

## API Endpoints

### Profile Management

Manage your personal profile and preferences.

**Base Path:** `/api/v1/user/profile`

#### Get Profile
```http
GET /api/v1/user/profile
```

**Description:** Retrieve your complete user profile including personal information, preferences, company associations, and license summary.

**Response:**
```json
{
  "success": true,
  "data": {
    "profile": {
      "id": "uuid",
      "email": "user@company.com",
      "first_name": "John",
      "last_name": "Doe",
      "avatar_url": "https://example.com/avatar.jpg",
      "phone": "+1234567890",
      "timezone": "America/New_York",
      "language": "en",
      "email_verified": true,
      "phone_verified": false,
      "two_factor_enabled": false,
      "last_sign_in_at": "2024-01-20T10:30:00Z",
      "created_at": "2024-01-15T09:00:00Z",
      "updated_at": "2024-01-20T10:30:00Z",
      "preferences": {
        "email_notifications": {
          "license_updates": true,
          "security_alerts": true,
          "product_updates": true,
          "marketing": false
        },
        "ui_preferences": {
          "theme": "auto",
          "language": "en",
          "timezone": "America/New_York",
          "date_format": "MM/DD/YYYY"
        }
      },
      "companies": [
        {
          "company_id": "uuid",
          "company_name": "Acme Corporation",
          "role": "end_user",
          "is_active": true,
          "joined_at": "2024-01-15T09:00:00Z"
        }
      ],
      "license_summary": {
        "total_licenses": 3,
        "active_licenses": 2,
        "expired_licenses": 1
      }
    }
  }
}
```

#### Update Profile
```http
PUT /api/v1/user/profile
```

**Description:** Update your personal information and preferences.

**Request Body:**
```json
{
  "first_name": "Jane",
  "last_name": "Smith",
  "phone": "+1987654321",
  "timezone": "Pacific/Pacific",
  "language": "es",
  "preferences": {
    "email_notifications": {
      "license_updates": true,
      "security_alerts": true,
      "product_updates": false,
      "marketing": false
    },
    "ui_preferences": {
      "theme": "dark",
      "language": "es",
      "timezone": "Pacific/Pacific",
      "date_format": "DD/MM/YYYY"
    }
  }
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "profile": {
      "id": "uuid",
      "email": "user@company.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "phone": "+1987654321",
      "timezone": "Pacific/Pacific",
      "language": "es",
      "updated_at": "2024-01-20T15:45:00Z",
      "preferences": {
        "email_notifications": {
          "license_updates": true,
          "security_alerts": true,
          "product_updates": false,
          "marketing": false
        },
        "ui_preferences": {
          "theme": "dark",
          "language": "es",
          "timezone": "Pacific/Pacific",
          "date_format": "DD/MM/YYYY"
        }
      }
    }
  }
}
```

### License Management

View and manage your licenses (read-only access).

**Base Path:** `/api/v1/user/licenses`

#### List Your Licenses
```http
GET /api/v1/user/licenses
```

**Description:** Retrieve paginated list of licenses assigned to your email address.

**Query Parameters:**
- `page` (integer): Page number (default: 1)
- `limit` (integer): Items per page (default: 20, max: 100)
- `status` (string): Filter by status (`active`, `expired`, `suspended`, `revoked`)
- `product_id` (string): Filter by product ID

**Response:**
```json
{
  "success": true,
  "data": {
    "licenses": [
      {
        "id": "uuid",
        "license_key": "LIC-XXX-XXX-XXX",
        "email": "user@company.com",
        "status": "active",
        "plan": "pro",
        "created_at": "2024-01-15T09:00:00Z",
        "expires_at": "2024-12-31T23:59:59Z",
        "updated_at": "2024-01-15T09:00:00Z",
        "product": {
          "id": "uuid",
          "name": "Pro Software",
          "description": "Professional software suite"
        },
        "company": {
          "id": "uuid",
          "name": "Acme Corporation"
        },
        "usage": {
          "device_count": 2,
          "max_devices": 3,
          "session_count": 1,
          "last_validation_at": "2024-01-20T10:30:00Z",
          "total_validations": 150
        },
        "devices": [
          {
            "id": "uuid",
            "device_name": "John's MacBook",
            "platform": "macOS",
            "trust_level": "trusted",
            "last_seen_at": "2024-01-20T10:30:00Z",
            "is_active": true
          },
          {
            "id": "uuid",
            "device_name": "Work PC",
            "platform": "Windows",
            "trust_level": "verified",
            "last_seen_at": "2024-01-19T16:45:00Z",
            "is_active": true
          }
        ],
        "metadata": {
          "purchase_order": "PO-12345",
          "billing_cycle": "annual"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 3,
      "pages": 1
    },
    "summary": {
      "total_licenses": 3,
      "active_licenses": 2,
      "expired_licenses": 1,
      "total_devices": 4
    }
  }
}
```

#### Get License Details
```http
GET /api/v1/user/licenses/{id}
```

**Description:** Get detailed information about a specific license you own.

**Parameters:**
- `id` (path): License ID

**Response:**
```json
{
  "success": true,
  "data": {
    "license": {
      "id": "uuid",
      "license_key": "LIC-XXX-XXX-XXX",
      "email": "user@company.com",
      "status": "active",
      "plan": "pro",
      "created_at": "2024-01-15T09:00:00Z",
      "expires_at": "2024-12-31T23:59:59Z",
      "updated_at": "2024-01-15T09:00:00Z",
      "product": {
        "id": "uuid",
        "name": "Pro Software",
        "description": "Professional software suite",
        "version": "2.0",
        "category": "Productivity"
      },
      "company": {
        "id": "uuid",
        "name": "Acme Corporation",
        "support_email": "support@acme.com"
      },
      "usage": {
        "device_count": 2,
        "max_devices": 3,
        "session_count": 1,
        "last_validation_at": "2024-01-20T10:30:00Z",
        "total_validations": 150,
        "usage_analytics": {
          "daily_usage": [
            { "date": "2024-01-20", "validations": 25 },
            { "date": "2024-01-19", "validations": 18 }
          ],
          "device_usage": [
            { "device_id": "uuid", "validations": 120 },
            { "device_id": "uuid", "validations": 30 }
          ]
        }
      },
      "devices": [
        {
          "id": "uuid",
          "device_name": "John's MacBook",
          "platform": "macOS",
          "trust_level": "trusted",
          "last_seen_at": "2024-01-20T10:30:00Z",
          "is_active": true,
          "registered_at": "2024-01-15T09:30:00Z"
        }
      ],
      "metadata": {
        "purchase_order": "PO-12345",
        "billing_cycle": "annual",
        "support_level": "premium"
      }
    }
  }
}
```

## Data Models

### UserProfile
```typescript
interface UserProfile {
  id: string;
  email: string;
  first_name?: string;
  last_name?: string;
  avatar_url?: string;
  phone?: string;
  timezone?: string;
  language?: string;
  
  // Account information
  email_verified: boolean;
  phone_verified: boolean;
  two_factor_enabled: boolean;
  last_sign_in_at?: string;
  created_at: string;
  updated_at: string;
  
  // User preferences
  preferences?: {
    email_notifications?: {
      license_updates?: boolean;
      security_alerts?: boolean;
      product_updates?: boolean;
      marketing?: boolean;
    };
    ui_preferences?: {
      theme?: 'light' | 'dark' | 'auto';
      language?: string;
      timezone?: string;
      date_format?: string;
    };
  };
  
  // Company associations
  companies?: Array<{
    company_id: string;
    company_name: string;
    role: string;
    is_active: boolean;
    joined_at: string;
  }>;
  
  // License summary
  license_summary?: {
    total_licenses: number;
    active_licenses: number;
    expired_licenses: number;
  };
}
```

### UserLicense
```typescript
interface UserLicense {
  id: string;
  license_key: string;
  email: string;
  status: 'active' | 'expired' | 'suspended' | 'revoked';
  plan: string;
  created_at: string;
  expires_at?: string;
  updated_at: string;
  
  // Product information
  product: {
    id: string;
    name: string;
    description?: string;
  };
  
  // Company information
  company: {
    id: string;
    name: string;
  };
  
  // Usage information
  usage: {
    device_count: number;
    max_devices: number;
    session_count: number;
    last_validation_at?: string;
    total_validations: number;
  };
  
  // Device information
  devices?: Array<{
    id: string;
    device_name: string;
    platform: string;
    trust_level: string;
    last_seen_at: string;
    is_active: boolean;
  }>;
  
  // Metadata
  metadata?: Record<string, any>;
}
```

## Code Examples

### JavaScript/Node.js

```javascript
// Initialize API client
const API_BASE = 'https://yourdomain.com/api/v1';
const API_TOKEN = 'your_jwt_token';

const headers = {
  'Authorization': `Bearer ${API_TOKEN}`,
  'Content-Type': 'application/json'
};

// Get user profile
async function getProfile() {
  const response = await fetch(`${API_BASE}/user/profile`, {
    headers
  });
  return response.json();
}

// Update user profile
async function updateProfile(profileData) {
  const response = await fetch(`${API_BASE}/user/profile`, {
    method: 'PUT',
    headers,
    body: JSON.stringify(profileData)
  });
  return response.json();
}

// Get user licenses
async function getLicenses(filters = {}) {
  const params = new URLSearchParams(filters);
  const response = await fetch(`${API_BASE}/user/licenses?${params}`, {
    headers
  });
  return response.json();
}

// Get specific license details
async function getLicenseDetails(licenseId) {
  const response = await fetch(`${API_BASE}/user/licenses/${licenseId}`, {
    headers
  });
  return response.json();
}
```

### Python

```python
import requests
import json

class EndUserAPI:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    
    def get_profile(self):
        response = requests.get(
            f'{self.base_url}/user/profile',
            headers=self.headers
        )
        return response.json()
    
    def update_profile(self, profile_data):
        response = requests.put(
            f'{self.base_url}/user/profile',
            headers=self.headers,
            json=profile_data
        )
        return response.json()
    
    def get_licenses(self, **filters):
        response = requests.get(
            f'{self.base_url}/user/licenses',
            headers=self.headers,
            params=filters
        )
        return response.json()

# Usage
api = EndUserAPI(
    'https://yourdomain.com/api/v1',
    'your_jwt_token'
)

profile = api.get_profile()
print(json.dumps(profile, indent=2))
```

### cURL Examples

```bash
# Get user profile
curl -X GET "https://yourdomain.com/api/v1/user/profile" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

# Update profile preferences
curl -X PUT "https://yourdomain.com/api/v1/user/profile" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "preferences": {
      "email_notifications": {
        "license_updates": true,
        "security_alerts": true
      },
      "ui_preferences": {
        "theme": "dark"
      }
    }
  }'

# Get user licenses
curl -X GET "https://yourdomain.com/api/v1/user/licenses?status=active&limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get specific license details
curl -X GET "https://yourdomain.com/api/v1/user/licenses/LICENSE_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## SDKs & Tools

### Available Resources

1. **Postman Collection**: Complete collection with pre-configured requests
2. **OpenAPI Specification**: Machine-readable API specification
3. **JavaScript SDK**: Official SDK for Node.js and browser
4. **Python SDK**: Official Python package

### Testing & Development

1. **Sandbox Environment**: Test all features safely
2. **API Explorer**: Interactive API documentation
3. **Mock Data**: Pre-populated test data

## Support & Resources

- **API Documentation**: Complete reference documentation
- **Developer Portal**: Additional resources and guides  
- **Status Page**: Real-time API status and uptime
- **Support**: Technical support for integration assistance

**Contact Information:**
- Email: support@bitcrate.co.uk
- Documentation: https://docs.bitcrate.co.uk
- Status: https://status.bitcrate.co.uk

---

*Last Updated: January 2024*  
*API Version: 1.0* 

📄 End User API Documentation