Spanning API Patterns

Spanning API Patterns

Status note

The MCP server (spanning-mcp) and SDK (@wyre-technology/node-spanning) are in development.

Overview

Spanning Cloud Backup provides daily SaaS backup for Microsoft 365, Google Workspace, and Salesforce. Each platform has its own REST API surface but a shared auth model.

Base URLs:

https://o365-api.spanningbackup.com/external/   (Microsoft 365)
https://api.spanningbackup.com/external/        (Google Workspace)
https://salesforce-api.spanningbackup.com/      (Salesforce)

The MCP server takes a platform credential field (m365 | gws | salesforce) plus the appropriate region if applicable.

Anti-triggers

• Datto SaaS Protection — Kaseya's other cloud-to-cloud backup product, covering the same Microsoft 365 and Google Workspace workloads under separate credentials and a separate API; use datto-saas-protection-api-patterns.
• Appliance-based backup — SIRIS/Alto and Unitrends protect servers and images, not SaaS tenants; use datto-bcdr-api-patterns or unitrends-api-patterns.

Authentication

Spanning uses HTTP Basic auth per the public OpenAPI spec (http://o365-docs.spanningbackup.com/swagger/json):

Authorization: Basic base64(<admin_email>:<api_token>)

The admin email and API token are pair-bound — both must match the pair on file in the Spanning admin console or the API returns 401.

Token issuance:

1. Spanning admin console → Settings → API Token
2. Copy token (shown once)
3. Tokens are tenant-scoped — one per Spanning org

Object model

Org (a Spanning customer)
 └── User (a backed-up M365 / GWS / Salesforce user)
      └── Backup runs (one per day per service per user)
           └── Restorable items (mail / drive / calendar / records)

Common endpoints (M365 example)

Google Workspace and Salesforce surfaces mirror this with platform-appropriate substitutions.

Pagination

Cursor-based:

GET /external/users?limit=100
→ { items: [...], next: "<cursor>" }

GET /external/users?limit=100&cursor=<cursor>

Default limit 50, max 200.

Restore operations

Async, similar pattern to Datto SaaS Protection:

1. POST /external/users/{userId}/services/{service}/restores
   body: { items: [...], restoreDestination: "..." }
   → { restoreId, status: "queued" }
2. Poll GET /external/restores/{restoreId} every 30s
3. status: queued → running → completed | failed

Rate limits

100 req/min per token. HTTP 429 includes Retry-After. Long-running list operations (e.g. iterating audit logs across 90 days) should chunk by date and serialize.

Error handling

Gotchas

• Admin email + token must match: The token is bound to the admin email. If either is wrong, the API returns 401 with a generic message — surface a clear "verify both fields" error.
• Platform-specific URL bases: A token that works for M365 won't work against the GWS endpoint. Cross-platform org reporting requires separate tokens (or one platform-agnostic token at the partner level for partner-tier customers).
• Spanning vs Datto SaaS Protection: Despite shared Kaseya branding, these are different products. Don't mix tokens.
• Salesforce API quirks: The Salesforce surface uses Salesforce object IDs (15- or 18-character) rather than the user-friendly identifiers used by M365/GWS endpoints.

Related skills

When the build-out lands, expect domain skills for: users, backups, restores, audit, license.