Major update: Cove API tested - critical limitations discovered

Added comprehensive API test results document (with ChatGPT assistance): - docs/cove_data_protection_api_calls_known_info.md Key findings from live API testing: - API works: JSON-RPC 2.0 at https://api.backup.management/jsonapi - Authentication: Login method → visa token - Method tested: EnumerateAccountStatistics (limited success) CRITICAL LIMITATIONS DISCOVERED: - Security error 13501 blocks most useful columns - No backup status fields (success/failed/warning) accessible - No error messages (D02Fxx/D03Fxx ranges blocked) - No reliable backup timestamps - No detailed run history - API users are customer-scoped (not MSP-level) - EnumerateAccounts method always fails (security block) Working columns (allow-list only): - I1 (account ID), I14 (storage bytes), I18 (hostname) - D01F00-D01F07, D09F00 (numeric metrics, semantics unclear) Impact on Backupchecks: - Current API access INSUFFICIENT for backup monitoring - Cannot determine if backups succeeded or failed - No error messages to show users - Core Backupchecks functionality not achievable with current API Added decision matrix with 4 options: A. Implement metrics-only (low value, storage usage only) B. Request expanded access from N-able (requires vendor cooperation) C. Explore alternative methods (webhooks, reports, email) D. Defer integration until better API access available Recommendation: Option B or C before implementing anything - Contact N-able support for MSP-level API user + expanded columns - OR investigate if Cove has webhook/reporting alternatives This represents a significant blocker for Cove integration. Full integration requires either vendor cooperation or alternative approach. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-10 16:55:31 +01:00 · 2026-02-10 16:55:31 +01:00 · 6674d40f4b
commit 6674d40f4b
parent 32e68d7209
2 changed files with 344 additions and 2 deletions
--- a/TODO-cove-data-protection.md
+++ b/TODO-cove-data-protection.md
@ -286,6 +286,136 @@ Other backup systems that use APIs:

 ---

+## ⚠️ 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!)
@ -497,8 +627,20 @@ Based on POC results, decide architecture approach and start implementation
 - ✅ **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
+- ✅ **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
--- a/docs/cove_data_protection_api_calls_known_info.md
+++ b/docs/cove_data_protection_api_calls_known_info.md
@ -0,0 +1,200 @@
+# Cove Data Protection (N-able Backup) – Known Information on API Calls
+
+Date: 2026-02-10
+Status: Research phase (validated with live testing)
+
+## Summary of current findings
+
+API access to Cove Data Protection via JSON-RPC **works**, but is **heavily restricted per tenant and per API user scope**. The API is usable for monitoring, but only with a **very limited, allow‑listed set of column codes**. Any request that includes a restricted column immediately fails with:
+
+```
+Operation failed because of security reasons (error 13501)
+```
+
+This behavior is consistent even when the API user has **SuperUser** and **SecurityOfficer** roles.
+
+---
+
+## Authentication model (confirmed)
+
+- Endpoint: https://api.backup.management/jsonapi
+- Protocol: JSON‑RPC 2.0
+- Method: POST only
+- Authentication flow:
+  1. Login method is called
+  2. Response returns a **visa** token (top‑level field)
+  3. The visa **must be included in every subsequent call**
+  4. Cove may return a new visa in later responses (token chaining)
+
+### Login request (working)
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "Login",
+  "params": {
+    "partner": "<EXACT customer/partner name>",
+    "username": "<api login name>",
+    "password": "<password>"
+  },
+  "id": "1"
+}
+```
+
+### Login response structure (important)
+
+```json
+{
+  "result": {
+    "result": {
+      "PartnerId": <number>,
+      "Name": "<login name>",
+      "Flags": ["SecurityOfficer","NonInteractive"]
+    }
+  },
+  "visa": "<visa token>"
+}
+```
+
+Notes:
+- `visa` is **not** inside `result`, but at top level
+- `PartnerId` is found at `result.result.PartnerId`
+
+---
+
+## API user scope (critical finding)
+
+- API users are **always bound to a single Partner (customer)** unless created at MSP/root level
+- In this environment, it is **not possible to create an MSP‑level API user**
+- All testing was therefore done with **customer‑scoped API users**
+
+Impact:
+- Cross‑customer enumeration is impossible
+- Only data belonging to the linked customer can be queried
+- Some enumerate/reporting calls are blocked regardless of role
+
+---
+
+## EnumerateAccountStatistics – what works and what does not
+
+### Method
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "EnumerateAccountStatistics",
+  "visa": "<visa>",
+  "params": {
+    "query": {
+      "PartnerId": <partner_id>,
+      "SelectionMode": "Merged",
+      "StartRecordNumber": 0,
+      "RecordsCount": 50,
+      "Columns": [ ... ]
+    }
+  }
+}
+```
+
+### Mandatory behavior
+
+- **Columns are required**; omitting them returns `result: null`
+- The API behaves as an **allow‑list**:
+  - If *any* requested column is restricted, the **entire call fails** with error 13501
+
+### Confirmed working (safe) column set
+
+The following column set works reliably:
+
+- I1  → account / device / tenant identifier
+- I14 → used storage (bytes)
+- I18 → computer name (if applicable)
+- D01F00 – D01F07 → numeric metrics (exact semantics TBD)
+- D09F00 → numeric status/category code
+
+Example (validated working):
+
+```json
+"Columns": [
+  "I1","I14","I18",
+  "D01F00","D01F01","D01F02","D01F03",
+  "D01F04","D01F05","D01F06","D01F07",
+  "D09F00"
+]
+```
+
+### Confirmed restricted (cause security error 13501)
+
+- Entire D02Fxx range
+- Entire D03Fxx range
+- Broad I‑ranges (e.g. I1–I10 batches)
+- Many individually tested I‑codes not in the safe set
+
+Even adding **one restricted code** causes the entire call to fail.
+
+---
+
+## EnumerateAccounts
+
+- Method consistently fails with `Operation failed because of security reasons`
+- This applies even with:
+  - SuperUser role
+  - SecurityOfficer flag enabled
+
+Conclusion:
+- EnumerateAccounts is **not usable** in this tenant for customer‑scoped API users
+
+---
+
+## Other tested methods
+
+- EnumerateStatistics → Method not found
+- GetPartnerInfo → works only for basic partner metadata (not statistics)
+
+---
+
+## Practical implications for BackupChecks
+
+What **is possible**:
+- Enumerate accounts implicitly via EnumerateAccountStatistics
+- Identify devices/accounts via AccountId + I1/I18
+- Collect storage usage (I14)
+- Collect numeric status/metrics via D01Fxx and D09F00
+
+What is **not possible (via this API scope)**:
+- Reliable last backup timestamp
+- Explicit success / failure / warning text
+- Error messages
+- Enumerating devices via EnumerateAccounts
+- Cross‑customer aggregation
+
+### Suggested internal model mapping
+
+- Customer
+  - external_id = PartnerId
+
+- Job
+  - external_id = AccountId
+  - display_name = I1
+  - hostname = I18 (if present)
+
+- Run (limited)
+  - metrics only (bytes, counters)
+  - status must be **derived heuristically** from numeric fields (if possible)
+
+---
+
+## Open questions / next steps
+
+1. Confirm official meaning of:
+   - D01F00 – D01F07
+   - D09F00
+
+2. Investigate whether:
+   - A token‑based (non‑JSON‑RPC) reporting endpoint exists
+   - N‑able support can enable additional reporting columns
+   - An MSP‑level API user can be provisioned by N‑able
+
+3. Decide whether Cove integration in BackupChecks will be:
+   - Metrics‑only (no run result semantics)
+   - Or require vendor cooperation for expanded API access