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

Each integration provides its own setup and access flow. Slack brings vaults, ingots and one-time secrets into App Home, slash commands and dialogs, while vault keys are entered only on a brief SparkVault page; Slack processes the information entered or displayed in its interface. HubSpot and Salesforce files use SparkVault's vault and Forge access controls.

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

Secrets sent from Slack are free on every plan. HubSpot and Salesforce add no per-operation fees; standard vault storage and transfer pricing applies.

Fully Audited

The vault, file, and SparkLink operations an integration performs are recorded in your audit trail at the scope they touch, like any other; Slack additionally exposes usage analytics at GET /v1/apps/slack/analytics.

Authentication

Integration endpoints authenticate on four planes:

No integration holds your API key. HubSpot and Salesforce act for your account through a SparkVault credential that their OAuth callback obtains from SparkVault itself, never exposed to the browser, and every request they make with it answers to your account's plan, storage and bandwidth exactly as your own requests do. The Slack integration holds only the sessions its members start: each member signs in to SparkVault as themselves, and the app keeps that member's session, encrypted, to act as them in Slack with no more access than they have. Disconnecting, removing or re-authorizing the workspace ends every member's session, and each also expires on its own. There is no integration credential for you to create or rotate.

Response Format

All integration endpoints follow the standard SparkVault response format:

{
  "data": {
    // Integration-specific response fields
  },
  "meta": {
    "api_version": "1.2.828",
    "request_id": "7f3c9a2e5b1d4e8f9a6c2d4b-1k",
    "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": "7f3c9a2e5b1d4e8f9a6c2d4b-1k"
  }
}

Install Lifecycle API

Integrations are installed per account and managed through the /v1/apps endpoints. Listing and reading an integration take standard SparkVault authentication (JWT or API key). Installing, updating and uninstalling take the session of an admin or owner; an API key is refused (403). Every integration here connects through its OAuth Install Flow, so a direct install or update is refused (403).

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. Their SparkVault credential is minted between trusted services and is never exposed to browser JavaScript.
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

Every integration uninstalls user-initiated via DELETE /v1/apps/{app_id}/uninstall (the session of an admin or owner; an API key is refused); Slack's first asks Slack to remove the app from the workspace. Slack and HubSpot also uninstall automatically on their signed provider webhook: Slack app_uninstalled/tokens_revoked, HubSpot app.deauthorize. Salesforce has no uninstall webhook: a Salesforce session proves only that its user belongs to the org, not the authority to disconnect the org for everyone.

Available Integrations

Slack

Browse vaults, manage ingots, and share protected files or expiring, single-read secrets from Slack.

• /sparkvault, App Home and shortcuts for vaults and ingots in Slack, unlocked on a brief SparkVault page
• Durable files.sv shares and one-time x.sv SparkLinks, with access review before posting
• /share_secret and /secret for single-read Sparks
• Direct-message and channel destinations
• Recipient confirmation before reading
• Automatic expiration for unread secrets
• Workspace secret usage reporting

Pricing: Secrets are free on every plan. Files use normal storage and transfer capacity.

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 or DVAK
• Download and delete files from HubSpot; an upload opens the record's folder in SparkVault in a new tab

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 or DVAK
• Download and delete files from Salesforce; an upload opens the record's folder in SparkVault in a new tab

Package version: the panel requires version 1.8 of the SparkVault managed package. Earlier versions do not send the Salesforce session SparkVault verifies, so SparkVault refuses every request their panel makes.

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: 5000 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": 5000,
    "used": 15,
    "remaining": 4985,
    "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: Read what an integration did in the audit trail 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.