From 6674d40f4bc53358ffc0e393898906ab288bc143 Mon Sep 17 00:00:00 2001 From: Ivo Oskamp Date: Tue, 10 Feb 2026 16:55:31 +0100 Subject: [PATCH] Major update: Cove API tested - critical limitations discovered MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- TODO-cove-data-protection.md | 146 ++++++++++++- ...ve_data_protection_api_calls_known_info.md | 200 ++++++++++++++++++ 2 files changed, 344 insertions(+), 2 deletions(-) create mode 100644 docs/cove_data_protection_api_calls_known_info.md diff --git a/TODO-cove-data-protection.md b/TODO-cove-data-protection.md index b4387ea..93f88dd 100644 --- 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 diff --git a/docs/cove_data_protection_api_calls_known_info.md b/docs/cove_data_protection_api_calls_known_info.md new file mode 100644 index 0000000..1a34329 --- /dev/null +++ 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": "", + "username": "", + "password": "" + }, + "id": "1" +} +``` + +### Login response structure (important) + +```json +{ + "result": { + "result": { + "PartnerId": , + "Name": "", + "Flags": ["SecurityOfficer","NonInteractive"] + } + }, + "visa": "" +} +``` + +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": "", + "params": { + "query": { + "PartnerId": , + "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