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

• 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!

• 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:

  # 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

---

🚀 Next Steps

Immediate Actions (Ready to Start!)

1. Read API Documentation ✅ FOUND! Priority reading order:

1. Start here: Login/Auth - How to authenticate with your token
2. Then read: Construct a Call - Request format
3. Key endpoint: Enumerate Device Statistics - 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:

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

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)
• ✅ Identified: Key endpoints (enumerate-customers, enumerate-devices, enumerate-device-statistics)
• 🎯 Next action: Read authentication docs and test API calls in Postman

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