backupchecks/TODO-cove-data-protection.md

# TODO: Cove Data Protection Integration

**Date:** 2026-02-10
**Status:** Research phase
**Priority:** Medium

---

## 🎯 Goal

Integrate Cove Data Protection (formerly N-able Backup / SolarWinds Backup) into Backupchecks for backup status monitoring.

**Challenge:** Cove does NOT work with email notifications like other backup systems (Veeam, Synology, NAKIVO). We need to find an alternative method to import backup status information.

---

## 🔍 Research Questions

### 1. API Availability
- [x] Does Cove Data Protection have a public API? **YES - Confirmed in documentation**
- [ ] **CRITICAL:** How to enable/activate API access? (settings location, admin portal?)
- [ ] What authentication method does the API use? (API key, OAuth, basic auth?)
- [ ] Which endpoints are available for backup status?
- [ ] Is there rate limiting on the API?
- [ ] Documentation URL: ?
- [ ] Is API access available in all Cove subscription tiers or only specific plans?

### 2. Data Structure
- [ ] What information can we retrieve per backup job?
  - Job name
  - Status (success/warning/failed)
  - Start/end time
  - Backup type
  - Client/device name
  - Error messages
  - Objects/files backed up
- [ ] Is there a webhook system available?
- [ ] How often should the API be polled?

### 3. Multi-Tenancy
- [ ] Does Cove support multi-tenant setups? (MSP use case)
- [ ] Can we monitor multiple customers/partners from 1 account?
- [ ] How are permissions/access managed?

### 4. Integration Strategy
- [ ] **Option A: Scheduled Polling**
  - Cronjob that periodically calls API
  - Parse results to JobRun records
  - Pro: Simple, consistent with current flow
  - Con: Delay between backup and registration in system

- [ ] **Option B: Webhook/Push**
  - Cove sends notifications to our endpoint
  - Pro: Real-time updates
  - Con: Requires external endpoint, security considerations

- [ ] **Option C: Email Forwarding**
  - If Cove has email support after all (hidden setting?)
  - Pro: Reuses existing email import flow
  - Con: Possibly not available

---

## 📋 Technical Considerations

### Database Model
Current JobRun model expects:
- `mail_message_id` (FK) - how do we adapt this for API-sourced runs?
- Possible new field: `source_type` ("email" vs "api")
- Possible new field: `external_id` (Cove job ID)

### Parser System
Current parser system works with email content. For API:
- New "parser" concept for API responses?
- Or direct JobRun creation without parser layer?

### Architecture Options

**Option 1: Extend Email Import System**
```
API Poller → Pseudo-MailMessage → Existing Parser → JobRun
```
- Pro: Reuse existing flow
- Con: Hacky, email fields have no meaning

**Option 2: Parallel Import System**
```
API Poller → API Parser → JobRun (direct)
```
- Pro: Clean separation, no email dependency
- Con: Logic duplication

**Option 3: Unified Import Layer**
```
         → Email Import →
Unified  →                → Common Processor → JobRun
         → API Import   →
```
- Pro: Future-proof, scalable
- Con: Larger refactor

---

## 🔧 Implementation Steps (After Research)

### Phase 0: API Access Activation (FIRST!)
**Critical step before any development can begin:**

1. [ ] **Find API activation location**
   - Check Cove admin portal/dashboard
   - Look in: Settings → API / Integrations / Developer section
   - Check: Account settings, Company settings, Partner settings
   - Search documentation for: "API activation", "API access", "enable API"

2. [ ] **Generate API credentials**
   - API key generation
   - Client ID / Client Secret (if OAuth)
   - Note: which user/role can generate API keys?

3. [ ] **Document API base URL**
   - Production API endpoint
   - Sandbox/test environment (if available)
   - Regional endpoints (EU vs US?)

4. [ ] **Document API authentication flow**
   - Header format (Bearer token, API key in header, query param?)
   - Token expiration and refresh
   - Rate limit headers to watch

5. [ ] **Find API documentation portal**
   - Developer documentation URL
   - Interactive API explorer (Swagger/OpenAPI?)
   - Code examples/SDKs
   - Support channels for API questions

**Resources to check:**
- Cove admin portal: https://backup.management (or similar)
- N-able partner portal
- Cove knowledge base / support docs
- Contact Cove support for API access instructions

### Phase 1: API Research & POC

**Step 1: Find API Base URL**
- [ ] Check Cove admin portal for API documentation link
- [ ] Common patterns to try:
  - `https://api.backup.management/`
  - `https://api.cove.n-able.com/`
  - `https://backup.management/api/`
  - `https://cloudbackup.management/api/`
- [ ] Check API user creation page for hints/links
- [ ] Look for "API Documentation" or "Developer" menu in portal

**Step 2: Test Authentication**
- [ ] Determine token format (Bearer token? API key header? Query param?)
- [ ] Common authentication patterns to test:
  ```bash
  # Option 1: Bearer token
  curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/endpoint

  # Option 2: API Key header
  curl -H "X-API-Key: YOUR_TOKEN" https://api.example.com/endpoint

  # Option 3: Custom header
  curl -H "X-Auth-Token: YOUR_TOKEN" https://api.example.com/endpoint
  ```
- [ ] Test with simple endpoint (e.g., `/api/v1/status`, `/api/accounts`, `/api/devices`)

**Step 3: Discover Available Endpoints**
- [ ] Find API documentation/reference
- [ ] Look for OpenAPI/Swagger spec
- [ ] Key endpoints we need:
  - List customers/accounts
  - List backup devices/jobs
  - Get backup job history
  - Get backup job status/details
  - Get backup run results (success/failed/warnings)

**Step 4: Test Data Retrieval**
- [ ] Test listing customers (verify top-level access works)
- [ ] Test listing backup jobs for one customer
- [ ] Test retrieving details for one backup job
- [ ] Document response format (JSON structure)
- [ ] Save example API responses for reference

**Step 5: Proof of Concept Script**
1. [ ] Create standalone Python script (outside Backupchecks)
2. [ ] Test authentication and data retrieval
3. [ ] Parse API response to extract key fields
4. [ ] Mapping of Cove data → Backupchecks JobRun model
5. [ ] Document findings in this TODO

### Phase 2: Database Changes
1. [ ] Decide: extend MailMessage model or new source type?
2. [ ] Migration: add `source_type` field to JobRun
3. [ ] Migration: add `external_id` field to JobRun
4. [ ] Update constraints/validations

### Phase 3: Import Mechanism
1. [ ] New file: `containers/backupchecks/src/backend/app/cove_importer.py`
2. [ ] API client for Cove
3. [ ] Data transformation to JobRun format
4. [ ] Error handling & retry logic
5. [ ] Logging & audit trail

### Phase 4: Scheduling
1. [ ] Cronjob/scheduled task for polling (every 15 min?)
2. [ ] Or: webhook endpoint if Cove supports it
3. [ ] Rate limiting & throttling
4. [ ] Duplicate detection (avoid double imports)

### Phase 5: UI Updates
1. [ ] Job Details: indication that job is from API (not email)
2. [ ] No "Download EML" button for API-sourced runs
3. [ ] Possibly different metadata display

---

## 📚 References

### Cove Data Protection
- **Product name:** Cove Data Protection (formerly N-able Backup, SolarWinds Backup)
- **Website:** https://www.n-able.com/products/cove-data-protection
- **API Docs:** [TODO: add link after research]
- **Support:** [TODO: contact info]

### Similar Integrations
Other backup systems that use APIs:
- Veeam: Has both email and REST API
- Acronis: REST API available
- MSP360: API for management

### Resources
- [ ] API documentation (yet to find)
- [ ] SDK/Client libraries available?
- [ ] Community/forum for integration questions?
- [ ] Example code/integrations?

---

## ❓ Open Questions

1. **Performance:** How many Cove jobs do we need to monitor? (impact on polling frequency)
2. **Historical Data:** Can we retrieve old backup runs, or only new ones?
3. **Filtering:** Can we apply filters (only failed jobs, specific clients)?
4. **Authentication:** Where do we store Cove API credentials? (SystemSettings?)
5. **Multi-Account:** Do we support multiple Cove accounts? (MSP scenario)

---

## 🎯 Success Criteria

### Minimum Viable Product (MVP)
- [ ] Backup runs from Cove are automatically imported
- [ ] Status (success/warning/failed) displayed correctly
- [ ] Job name and timestamp available
- [ ] Visible in Daily Jobs & Run Checks
- [ ] Errors and warnings are shown

### Nice to Have
- [ ] Real-time import (webhook instead of polling)
- [ ] Backup object details (individual files/folders)
- [ ] Retry history
- [ ] Storage usage metrics
- [ ] Multi-tenant support

---

## 🚀 Next Steps

### Immediate Actions (Ready to Start!)

**1. Find API Documentation**
- Check Cove admin portal for "API" or "Developer" section
- Look for documentation links on the API user creation page
- Search Cove knowledge base for "API documentation"
- Try common API base URLs with `/docs` or `/swagger` endpoints

**2. Quick API Test** (can be done now with token!)
Try these curl commands to test authentication:

```bash
# Replace YOUR_TOKEN with actual token from https://backup.management/#/api-users
# Try different authentication methods and endpoints:

# Test 1: Bearer token + accounts endpoint
curl -v -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.backup.management/api/accounts

# Test 2: API Key header
curl -v -H "X-API-Key: YOUR_TOKEN" \
  https://api.backup.management/api/accounts

# Test 3: Alternative base URL
curl -v -H "Authorization: Bearer YOUR_TOKEN" \
  https://backup.management/api/accounts

# Test 4: Check for API documentation
curl https://api.backup.management/swagger
curl https://api.backup.management/docs
curl https://backup.management/api/docs

# Test 5: Try common endpoints
curl -v -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.backup.management/api/customers

curl -v -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.backup.management/api/devices

# Note: Use -v flag to see full HTTP response including headers
# Look for authentication errors vs 404 errors to determine correct URL/auth
```

**3. Document Findings**
After successful API call, document in this file:
- Working API base URL
- Correct authentication header format
- Available endpoints discovered
- Example response format

**4. Create POC Script**
Once API works, create standalone Python test script:
```python
import requests

# Test script to retrieve Cove backup data
token = "YOUR_TOKEN"
base_url = "https://api.example.com"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Get list of customers
response = requests.get(f"{base_url}/api/customers", headers=headers)
print(response.json())
```

**5. Plan Integration**
Based on POC results, decide architecture approach and start implementation

**Status:** Ready for API testing - token available!

---

## 📝 Notes

- This TODO document should be updated after each research step
- Add API examples as soon as available
- Document edge cases and limitations
- Consider security implications (API key storage, rate limits, etc.)

### Current Status (2026-02-10)
- ✅ **Confirmed:** Cove Data Protection HAS API access (mentioned in documentation)
- ✅ **Found:** API user creation location in Cove portal
- ✅ **Created:** API user with SuperUser role and token
- ❓ **Testing needed:** API base URL and authentication method
- ❓ **Unknown:** Available endpoints and documentation
- 🎯 **Next action:** Test API access with token and find documentation

### API Credentials (Created)
- **Authentication:** Token-based
- **Role:** SuperUser (full access)
- **Scope:** Top-level customer (access to all sub-customers)
- **Token:** Generated (store securely!)
- **Portal URL:** https://backup.management
- **API User Management:** https://backup.management/#/api-users

**IMPORTANT:** Store token in secure location (password manager) - cannot be retrieved again if lost!

### Likely API Base URLs to Test
Based on portal URL `backup.management`:
1. `https://api.backup.management` (most common pattern)
2. `https://backup.management/api`
3. `https://api.backup.management/jsonapi` (some backup systems use this)
4. Check API user page for hints or documentation links

### Possible Admin Portal Locations
Check these sections in Cove dashboard:
- Settings → API Keys / Developer
- Settings → Integrations
- Account → API Access
- Partner Portal → API Management
- Company Settings → Advanced → API

### Support Channels
If API activation is not obvious:
- Cove support ticket: Ask "How do I enable API access for backup monitoring?"
- N-able partner support (if MSP)
- Check Cove community forums
- Review onboarding documentation for API mentions