self-serve-integration-service/docs/AUTHENTICATION_ARCHITECTURE.md

Self-Serve Integration Service for managing multiple funder integrations including REST APIs, SOAP APIs, and UI automation

# Authentication Architecture

## Overview

The Self-Serve Integration Service uses authentication middleware to protect sensitive endpoints while keeping certain read-only endpoints public.

---


## 🔓 Public Endpoints (No Authentication Required)

### Health & Monitoring
| Endpoint | Methods | Description |
|----------|---------|-------------|
| `/health` | GET | Health check endpoints |
| `/webhooks` | POST | Webhook endpoints for external systems |

### Funder Information (Public Read Access)
| Endpoint | Methods | Description |
|----------|---------|-------------|
| `/api/funders` | GET | List all funders with optional filtering (status, integrationType, active) |
| `/api/funders/:id` | GET | Get specific funder by UUID |
| `/api/funders/code/:code` | GET | Get funder by code (e.g., "LEX", "ALPH") |
| `/api/funders/:id/performance` | GET | Get funder performance metrics |

---


## 🔒 Protected Endpoints (Authentication Required)

### Funder Management (Write Operations)
| Endpoint | Methods | Auth Type | Description |
|----------|---------|-----------|-------------|
| `/api/funders` | POST | JWT or HMAC | Create new funder |
| `/api/funders/:id` | PUT | JWT or HMAC | Update funder |
| `/api/funders/:id` | DELETE | JWT or HMAC | Delete funder (soft delete) |
| `/api/funders/:id/credentials` | POST | JWT or HMAC | Add credentials to funder |
| `/api/funders/credentials/:credentialId` | PUT | JWT or HMAC | Update credential |
| `/api/funders/credentials/:credentialId` | DELETE | JWT or HMAC | Delete credential |
| `/api/funders/:id/test-connection` | POST | JWT or HMAC | Test funder connection |
| `/api/funders/:id/validate` | POST | JWT or HMAC | Validate funder configuration |

### Other Protected Endpoints
| Endpoint | Methods | Auth Type | Description |
|----------|---------|-----------|-------------|
| `/api/integration` | ALL | JWT or HMAC | Integration service endpoints |
| `/api/vehicles` | ALL | JWT or HMAC | Vehicle management |
| `/api/customers` | ALL | JWT or HMAC | Customer management |
| `/api/quotes` | ALL | JWT or HMAC | Quote management |
| `/api/proposals` | ALL | JWT or HMAC | Proposal management |

---


## 🔐 Authentication Methods

### 1. JWT Token Authentication
Used for user and OAuth client authentication via API Gateway.

**Example:**
```bash
GET /api/funders/ALPH
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### 2. HMAC Request Signing
Used for service-to-service communication.

**Example:**
```bash
POST /api/funders
X-Service-Name: order-service
X-Timestamp: 1697280000000
X-Signature: base64-encoded-hmac-signature
```

---


## 🎯 Usage Examples

### Public Access (No Token Required)

**List all active funders:**
```bash
GET https://api.yourdomain.com/api/funders?status=ACTIVE
```

**Get funder by code:**
```bash
GET https://api.yourdomain.com/api/funders/code/LEX
```

**Get funder performance:**
```bash
GET https://api.yourdomain.com/api/funders/123e4567-e89b-12d3-a456-426614174000/performance
```

### Protected Access (Token Required)

**Create new funder:**
```bash
POST https://api.yourdomain.com/api/funders
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Alphabet Fleet Services",
  "code": "ALPH",
  "displayName": "Alphabet Fleet Services",
  "integrationType": "REST_API",
  "baseUrl": "https://api.alphabet.co.uk",
  "supportedQuoteTypes": ["PERSONAL_CONTRACT_PURCHASE"],
  "supportedProposalTypes": ["PERSONAL_CONTRACT_PURCHASE"],
  "credentials": [
    {
      "name": "API Key",
      "value": "your-api-key",
      "environment": "LIVE"
    }
  ]
}
```

---


## 🔒 Security Considerations

### Public Endpoints
- **Funder list endpoints are public** to allow frontend applications to display available funders without authentication
- Sensitive information (credentials, API keys) is **never returned** in public endpoints
- Rate limiting should be applied to prevent abuse
- Consider implementing caching for frequently accessed public data

### Protected Endpoints
- All write operations (POST, PUT, DELETE) require authentication
- Credential management endpoints are always protected
- Admin-only operations should have additional role-based access control

---


## 📊 Route Configuration Summary

```typescript
// self-serve-integration-service/src/index.ts

// Public routes
app.use('/health', healthRoutes);
app.use('/webhooks', webhookRoutes);

// Protected routes (authentication applied globally)
app.use('/api/integration', authMiddleware, integrationRoutes);
app.use('/api/vehicles', authMiddleware, vehicleRoutes);
app.use('/api/customers', authMiddleware, customerRoutes);
app.use('/api/quotes', authMiddleware, quoteRoutes);
app.use('/api/proposals', authMiddleware, proposalRoutes);

// Mixed authentication (handled per-route in funderRoutes.ts)
app.use('/api/funders', funderRoutes); // Public GET, Protected POST/PUT/DELETE
```

---


**Last Updated:** October 15, 2025  
**Version:** 1.2.0  
**Change:** Made GET endpoints for `/api/funders` public while keeping POST/PUT/DELETE protected