Integrations v1

Overview

Integrations are installable, OAuth-connected, per-account additions that connect SparkVault to external systems. They are distinct from global Products, which are always available and never require installation, and from platform Elements (Entropy, Sparks, SparkLinks, Vaults, Ingots), which are the primitives everything else composes over.

Why Use Integrations?

Zero Cryptographic Expertise Required

No key management or protocol work. Slack secrets are burn-after-read Sparks sealed with post-quantum encryption (ML-KEM-1024). HubSpot and Salesforce files are protected with Triple Zero-Trust encryption via Forge. Install, connect, and use.

Tenant and Record Isolation by Design

The CRM integrations serve many portal/org users against one shared installation without ever sharing access: vault unseals mint per-user VAT sessions keyed to the verified CRM user, and every download or delete is verified against the requesting record's folder, enforcing per-record isolation within a tenant.

Predictable Pricing

Slack uses standard Spark pricing: $0.001 per secret sent, free to read. HubSpot and Salesforce add no per-operation fees; standard vault storage and transfer pricing applies.

Fully Audited

Every integration operation is logged with timestamp, account, parameters, and result status. Retrieve integration-scoped audit logs with GET /v1/audit-logs/apps/:app_slug; Slack additionally exposes usage analytics at GET /v1/apps/slack/analytics.

Authentication

Integration endpoints authenticate on three planes:

Installed integrations use pass-through authentication: your JWT session or API key flows from user to integration to core API. There is no integration-specific credential binding to manage.

Response Format

All integration endpoints follow the standard SparkVault response format:

{
  "data": {
    // Integration-specific response fields
  },
  "meta": {
    "api_version": "1.2.828",
    "request_id": "req_a1b2c3d4e5f6",
    "response_ms": 42,
    "timestamp": 1783036800
  }
}

Authenticated success responses also carry meta.quota: your account's current rate-limit status (see Rate Limits).

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid app_id"
  },
  "meta": {
    "api_version": "1.2.828",
    "request_id": "req_a1b2c3d4e5f6"
  }
}

Install Lifecycle API

Integrations are installed per account and managed through the /v1/apps endpoints. All five require standard SparkVault authentication (JWT or API key); install, update, and uninstall additionally require an admin or owner role.

curl https://api.sparkvault.com/v1/apps \
  -H "X-API-Key: sv_live_abc123xyz789..."

{
  "data": {
    "installed": [
      {
        "app_id": "slack",
        "status": "active",
        "installed_at": 1783036800,
        "settings": {}
      }
    ],
    "available": ["slack", "hubspot", "salesforce"]
  }
}

OAuth Install Flow

Every integration requires an OAuth authorization on the external service. The flow is the same for all three:

1. Authorize on the provider: Start the install from app.sparkvault.com/integrations. You are redirected to the provider's consent screen.
2. Exchange the code: After the provider redirects back, the frontend posts the authorization code to the integration's OAuth callback under your SparkVault session (JWT): POST /v1/apps/{slack|hubspot|salesforce}/oauth/callback with { code, redirect_uri }. The CRM integrations additionally send the selected vault_id and the installing user's sv_refresh_token; see each integration's page for the full callback body.
3. Server-side validation: The backend exchanges the code with the provider and validates the grant. Slack requires the commands and chat:write bot scopes and is workspace-scoped. Org-wide Enterprise Grid installs are rejected. HubSpot and Salesforce verify the selected vault's ownership server-side with the caller's own token, so an installation can never bind to someone else's vault.
4. Installation created: On success the installation is created. Slack and Salesforce re-authorize an existing active install in place with a fresh token set (the recovery path for a revoked or expired connection); HubSpot requires uninstalling before reinstalling.

curl -X POST https://api.sparkvault.com/v1/apps/slack/oauth/callback \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "slack_oauth_code",
    "redirect_uri": "https://app.sparkvault.com/apps/slack/oauth/callback"
  }'

{
  "data": {
    "installed": true,
    "team_id": "T0123456789",
    "team_name": "Acme Corp",
    "account_id": "acc_xyz789..."
  }
}

Uninstalling

Each integration uninstalls two ways: user-initiated via DELETE /v1/apps/{app_id}/uninstall (JWT or API key), or automatically via provider webhook: Slack app_uninstalled/tokens_revoked, HubSpot app.deauthorize, Salesforce app.uninstall.

Available Integrations

Slack

Send self-destructing secrets directly in Slack with the /secret command.

• /secret slash command
• Send to users, groups, or channels
• Post-quantum encryption (ML-KEM-1024)
• Burn-after-read guarantee
• Configurable expiration (1 minute to 24 hours)
• Usage analytics by Slack user

Pricing: Standard Spark pricing ($0.001 per secret sent, free to read).

View full Slack documentation →

HubSpot

Encrypted file storage on HubSpot CRM records. Access vault files directly from Contact, Company, Deal, and Ticket tabs.

• SparkVault Files tab on CRM records
• Folder-per-record organization (Contacts, Companies, Deals, Tickets)
• Triple Zero-Trust encryption via Forge
• Vault unseal via VMK, DVAK, or SparkSync mobile
• Upload, download, and delete files from HubSpot

Pricing: Standard vault storage and transfer pricing applies. No additional per-operation fees.

View full HubSpot documentation →

Salesforce

Encrypted file storage on Salesforce CRM records. Access vault files directly from Account, Contact, Opportunity, and Case pages.

• SparkVault Files panel on CRM records
• Folder-per-record organization (Accounts, Contacts, Opportunities, Cases)
• Triple Zero-Trust encryption via Forge
• Vault unseal via VMK, DVAK, or SparkSync mobile
• Upload, download, and delete files from Salesforce

Pricing: Standard vault storage and transfer pricing applies. No additional per-operation fees.

View full Salesforce documentation →

Common Error Codes

Rate Limits

There are no per-integration rate limits. Rate limiting is account-wide: 300 operations per minute in a fixed 60-second window, applied to every authenticated API call. The limiter fails closed: if the rate-limit check itself cannot complete, the request is rejected rather than let through.

Authenticated success responses report your current status in meta.quota:

{
  "quota": {
    "limit": 300,
    "used": 15,
    "remaining": 285,
    "resets_at": 1783036860
  }
}

Exceeding the limit returns 429 RATE_LIMIT_EXCEEDED with a Retry-After header and details carrying limit, used, and resets_at.

Best Practices

• Use scoped API keys: Create separate keys per application and rotate them regularly.
• Handle errors gracefully: Implement proper error handling and retry logic with exponential backoff for transient failures.
• Monitor usage: Retrieve integration-scoped audit logs with GET /v1/audit-logs/apps/:app_slug and Slack usage analytics with GET /v1/apps/slack/analytics. Account-wide usage and costs live in the Reporting API.
• Cache when appropriate: Some responses can be cached briefly to reduce API calls, but never cache sensitive data or security-critical values.
• Validate inputs client-side: Reduce API calls by validating parameters before sending requests.