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: Read Authentication Documentation** ✅ DOCUMENTATION FOUND!
- [x] API documentation located
- [ ] **Read:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/login.htm
- [ ] **Read:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/construct-a-call.htm
- [ ] Document API base URL from docs
- [ ] Document authentication flow (likely JSON-RPC style based on "construct-a-call")
- [ ] Note any required request format (headers, body structure)

**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 Documentation Base:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/

### JSON API Documentation (Found!)

**Core Documentation:**
- 📘 **API Home:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/home.htm
- 🔑 **Login/Authentication:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/login.htm
- 🔧 **Construct API Calls:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/construct-a-call.htm

**Key Endpoints for Backupchecks:**
- 👥 **Enumerate Customers:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/enumerate-customers.htm
- 💻 **Enumerate Devices:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/enumerate-devices.htm
- 📊 **Enumerate Device Statistics:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/enumerate-device-statistics.htm

**Reference:**
- 📋 **API Column Codes:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/API-column-codes.htm
- 📋 **Legacy Column Codes:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/API-column-codes-legacy.htm
- 📐 **Schema Documentation:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/how-to-schema.htm

**Other Resources:**
- 🏗️ **Architecture Guide:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/Architecture-and-Security/Cove-Architecture-Guide.htm
- 🔒 **Security Guide:** https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/Architecture-and-Security/Cove-Security-Guide.htm

**Note:** API docs are in "unused" folder - likely legacy but still functional!

### 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

---

## ⚠️ Critical Limitations Discovered (2026-02-10)

### What the API CAN provide:
- ✅ Account/device identifiers (I1)
- ✅ Storage usage metrics (I14 - bytes used)
- ✅ Computer/hostname (I18)
- ✅ Numeric metrics (D01F00-D01F07, D09F00)
- ✅ Basic partner metadata

### What the API CANNOT provide (security restrictions):
- ❌ **Last backup timestamp** - No reliable date/time fields accessible
- ❌ **Backup status** (success/failed/warning) - No explicit status fields
- ❌ **Error messages** - All D02Fxx/D03Fxx ranges blocked
- ❌ **Backup run history** - No detailed run information
- ❌ **Cross-customer aggregation** - API users are customer-scoped
- ❌ **Device enumeration** - EnumerateAccounts method blocked (error 13501)

### Root Cause
**Security error 13501** ("Operation failed because of security reasons") occurs when:
- Any restricted column code is requested in EnumerateAccountStatistics
- EnumerateAccounts method is called (always fails)
- This applies even with SuperUser + SecurityOfficer roles

**Column restrictions are per-tenant and not documented.** The allow-list is extremely limited.

### Impact on Backupchecks Integration
**Current API access is insufficient for backup monitoring** because:
1. No way to determine if a backup succeeded or failed
2. No error messages to display to users
3. No timestamps to track backup frequency
4. Cannot import backup "runs" in meaningful way

**Possible with current API:**
- Storage usage dashboard only
- Device inventory list
- But NOT backup status monitoring (core Backupchecks function)

---

## 🔀 Decision Point: Integration Feasibility

### Option A: Implement Metrics-Only Integration
**Pros:**
- Can display storage usage per device
- Simple implementation
- Works with current API access

**Cons:**
- Does NOT meet core Backupchecks requirement (backup status monitoring)
- No success/failure tracking
- No alerting on backup issues
- Limited value compared to email-based systems

**Effort:** Low (2-3 days)
**Value:** Low (storage metrics only, no backup monitoring)

### Option B: Request Expanded API Access from N-able
**Contact N-able support and request:**
1. MSP-level API user capability (cross-customer access)
2. Access to restricted column codes:
   - Backup timestamps (last successful backup)
   - Status fields (success/warning/failed)
   - Error message fields (D02Fxx/D03Fxx)
   - Session/run history fields

**Pros:**
- Could enable full backup monitoring if granted
- Proper integration matching other backup systems

**Cons:**
- May require vendor cooperation
- No guarantee N-able will grant access
- Possible additional licensing costs?
- Timeline uncertain (support ticket process)

**Effort:** Unknown (depends on N-able response)
**Value:** High (if successful)

### Option C: Alternative Integration Methods
Explore if Cove has:
1. **Reporting API** (separate from JSON-RPC)
2. **Webhook system** (push notifications for backup events)
3. **Email notifications** (if available, use existing email parser)
4. **Export/CSV reports** (scheduled export that can be imported)

**Effort:** Medium (research required)
**Value:** Unknown

### Option D: Defer Integration
**Wait until:**
- Customer requests Cove support specifically
- N-able improves API capabilities
- Alternative integration method discovered

**Pros:**
- No wasted effort on limited implementation
- Focus on systems with better API support

**Cons:**
- Cove customers cannot use Backupchecks
- Competitive disadvantage if other MSPs support Cove

---

## 🎯 Recommended Next Steps

### Immediate (This Week)
1. **Decision:** Choose Option A, B, C, or D above
2. **If Option B (contact N-able):**
   - Open support ticket with N-able
   - Reference API user creation at https://backup.management/#/api-users
   - Explain need for expanded column access for monitoring solution
   - Attach findings from `/docker/develop/cove_data_protection_api_calls_known_info.md`
   - Ask specifically for:
     - MSP-level API user creation
     - Access to backup status/timestamp columns
     - Documentation of column codes semantics

3. **If Option C (alternative methods):**
   - Check Cove portal for webhook/reporting settings
   - Search N-able docs for "reporting API", "webhooks", "notifications"
   - Test if email notifications can be enabled per customer

### Long Term (Future)
- Monitor N-able API changelog for improvements
- Check if other MSPs have found workarounds
- Consider partnering with N-able for integration

---

## 🚀 Next Steps

### Immediate Actions (Ready to Start!)

**1. Read API Documentation** ✅ FOUND!
Priority reading order:
1. **Start here:** [Login/Auth](https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/login.htm) - How to authenticate with your token
2. **Then read:** [Construct a Call](https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/construct-a-call.htm) - Request format
3. **Key endpoint:** [Enumerate Device Statistics](https://documentation.n-able.com/covedataprotection/USERGUIDE/documentation/Content/unused/service-management/json-api/enumerate-device-statistics.htm) - This likely has backup job data!

**What to extract from docs:**
- API base URL/endpoint
- Request format (JSON-RPC? REST? POST body structure?)
- How to use the token in requests
- Response format examples
- Which fields contain backup status/results

**2. Quick API Test with Postman** (can be done now with token!)

### Postman Setup Instructions

**Step 1: Create New Request**
1. Open Postman
2. Click "New" → "HTTP Request"
3. Name it "Cove API - Test Authentication"

**Step 2: Configure Request**
- **Method:** GET
- **URL:** Try these in order:
  1. `https://api.backup.management/api/accounts`
  2. `https://backup.management/api/accounts`
  3. `https://api.backup.management/api/customers`

**Step 3: Add Authentication (try both methods)**

**Option A: Bearer Token**
- Go to "Authorization" tab
- Type: "Bearer Token"
- Token: `YOUR_TOKEN` (paste token from backup.management)

**Option B: API Key in Header**
- Go to "Headers" tab
- Add header:
  - Key: `X-API-Key`
  - Value: `YOUR_TOKEN`

**Step 4: Send Request and Analyze Response**

**Expected Results:**
- ✅ **200 OK** → Success! API works, save this configuration
  - Copy the JSON response → we'll analyze structure
  - Note which URL and auth method worked
  - Check for pagination info in response

- ❌ **401 Unauthorized** → Wrong auth method
  - Try other authentication option (Bearer vs X-API-Key)
  - Check if token was copied correctly

- ❌ **404 Not Found** → Wrong endpoint URL
  - Try alternative base URL (api.backup.management vs backup.management)
  - Try different endpoint (/api/customers, /api/devices)

- ❌ **403 Forbidden** → Token works but insufficient permissions
  - Verify API user has SuperUser role
  - Check customer scope selection

**Step 5: Discover Available Endpoints**

Once authentication works, try these endpoints:
```
GET /api/accounts
GET /api/customers
GET /api/devices
GET /api/jobs
GET /api/statistics
GET /api/sessions
```

For each successful endpoint, save:
- The request in Postman collection
- Example response in TODO or separate file
- Note any query parameters (page, limit, filter, etc.)

**Step 6: Look for API Documentation**

Try these URLs in browser or Postman:
- `https://api.backup.management/swagger`
- `https://api.backup.management/docs`
- `https://api.backup.management/api-docs`
- `https://backup.management/api/documentation`

**Step 7: Document Findings**

After successful testing, document in this TODO:
- ✅ Working API base URL
- ✅ Correct authentication method (Bearer vs header)
- ✅ List of available endpoints discovered
- ✅ JSON response structure examples
- ✅ Any pagination/filtering patterns
- ✅ Rate limits (check response headers: X-RateLimit-*)

### Postman Tips for This Project

**Save Everything:**
- Create a "Cove API" collection in Postman
- Save all working requests
- Export collection to JSON for documentation

**Use Variables:**
- Create Postman environment "Cove Production"
- Add variable: `cove_token` = your token
- Add variable: `cove_base_url` = working base URL
- Use `{{cove_token}}` and `{{cove_base_url}}` in requests

**Check Response Headers:**
- Look for `X-RateLimit-Limit` (API call limits)
- Look for `X-RateLimit-Remaining` (calls left)
- Look for `Link` header (pagination)

**Save Response Examples:**
- For each endpoint, save example response
- Use Postman's "Save Response" feature
- Or copy JSON to separate file for reference

**3. Document Findings**

**After successful Postman testing, update this TODO with:**

```markdown
## ✅ API Testing Results (Add after testing)

### Working Configuration
- **Base URL:** [fill in]
- **Authentication:** Bearer Token / X-API-Key header (circle one)
- **Token Location:** Authorization header / X-API-Key header (circle one)

### Available Endpoints Discovered
| Endpoint | Method | Purpose | Response Fields |
|----------|--------|---------|-----------------|
| /api/accounts | GET | List accounts | [list key fields] |
| /api/customers | GET | List customers | [list key fields] |
| /api/devices | GET | List backup devices | [list key fields] |
| /api/jobs | GET | List backup jobs | [list key fields] |

### Key Response Fields for Backupchecks Integration
From backup job/session endpoint:
- Job ID: `[field name]`
- Job Name: `[field name]`
- Status: `[field name]` (values: success/warning/failed)
- Start Time: `[field name]`
- End Time: `[field name]`
- Customer/Device: `[field name]`
- Error Messages: `[field name]`
- Backup Objects: `[field name or nested path]`

### Pagination
- Method: [Link headers / page parameter / cursor / none]
- Page size: [default and max]
- Total count: [available in response?]

### Rate Limiting
- Limit: [X requests per Y time]
- Headers: [X-RateLimit-* header names]

### API Documentation URL
- [URL if found, or "Not found" if unavailable]
```

**Save Postman Collection:**
- Export collection as JSON
- Save to: `/docker/develop/backupchecks/docs/cove-api-postman-collection.json`
- Or share Postman workspace link in this TODO

**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
- ✅ **Found:** Complete JSON API documentation (N-able docs site)
- ✅ **Tested:** API authentication and multiple methods (with ChatGPT assistance)
- ⚠️ **CRITICAL LIMITATION DISCOVERED:** API heavily restricted by column allow-list
- ⚠️ **BLOCKER:** No reliable backup status (success/failed/warning) available via API
- ⚠️ **BLOCKER:** No error messages, timestamps, or detailed run information accessible
- 🎯 **Next decision:** Determine if metrics-only integration is valuable OR contact N-able for expanded access

### Test Results Summary (see docs/cove_data_protection_api_calls_known_info.md)
- **Endpoint:** https://api.backup.management/jsonapi (JSON-RPC 2.0)
- **Authentication:** Login method → visa token → include in all subsequent calls
- **Working method:** EnumerateAccountStatistics (with limited columns)
- **Blocked method:** EnumerateAccounts (security error 13501)
- **Safe columns:** I1, I14, I18, D01F00-D01F07, D09F00
- **Restricted columns:** D02Fxx, D03Fxx ranges (cause entire request to fail)
- **Scope limitation:** API users are customer-scoped, not MSP-level

### 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