# HubSpot: SparkVault API Reference

> Encrypted file storage on every HubSpot Contact, Company, Deal, and Ticket: files encrypted through Forge and organized into a folder per CRM record.

Canonical: https://sparkvault.com/api/docs/integrations/hubspot/ · OpenAPI: https://sparkvault.com/openapi.yaml

## Overview

The HubSpot integration adds a **SparkVault Files** sidebar card and a full **SparkVault** tab to every Contact, Company, Deal, and Ticket record in your HubSpot portal. Files uploaded from a record are encrypted through [Forge](/api/docs/forge/) with SparkVault's Triple Zero-Trust model and stored as encrypted ingots in one of your [vaults](/api/docs/vaults/), automatically organized into a folder per CRM record. Nothing sensitive ever lives in HubSpot; the CRM only renders the card.

AES-256-GCM

Encryption via Forge

4 Record Types

Contacts, Companies, Deals, Tickets

Zero-Knowledge

Triple Zero-Trust Model

Per-Record

Folder Isolation

### Key Features

-   **SparkVault Files card on CRM records**: A native card on every Contact, Company, Deal, and Ticket
-   **Triple Zero-Trust encryption via Forge**: AES-256-GCM with keys derived from your vault's key hierarchy
-   **Folder-per-record organization**: Files are auto-organized by CRM record type and ID (no manual folder management)
-   **Vault unseal via VMK or DVAK**: Unseal directly from HubSpot without leaving the record
-   **Upload, download, and delete from HubSpot**: The full file lifecycle without switching tools

> **Security Model**
>
> File contents are never stored in or streamed through HubSpot: uploads and downloads move directly between your browser and Forge. HubSpot renders the card and relays signed control requests (file listings, unseal, download-link issuance); file contents never transit HubSpot. Once your vault is sealed, only your Vault Master Key can unlock the files; SparkVault employees cannot read them.

## How It Works

#### User Flow

1.  Open any Contact, Company, Deal, or Ticket record in HubSpot
2.  The SparkVault Files card loads on the record page
3.  Unseal your vault with your VMK or DVAK
4.  The card lists the encrypted files stored for that record
5.  Upload, download, or delete files; every operation is encrypted through Forge
6.  Your unseal session expires after one hour and the card returns to its sealed state

### Folder-per-Record Organization

Every CRM record maps to a deterministic folder in the vault you connected at install time: `{ObjectType}/{RecordID}`. Folders are created lazily on first upload; a record with no files has no folder.

| CRM Object | Vault Folder | Example |
| --- | --- | --- |
| Contact | `Contacts/{record_id}` | `Contacts/501` |
| Company | `Companies/{record_id}` | `Companies/9021` |
| Deal | `Deals/{record_id}` | `Deals/3307` |
| Ticket | `Tickets/{record_id}` | `Tickets/118` |

> **Per-User Unseal Sessions**
>
> Unsealing is scoped to the individual HubSpot user who entered the key. Each teammate in your portal must unseal the vault themselves; one user's unseal never grants vault access to the rest of the portal.

## Installation

The HubSpot integration is installed via OAuth from the SparkVault dashboard. During installation you choose which vault stores your CRM files; SparkVault verifies server-side that you own the selected vault before completing the connection.

### Installation Steps

1.  Sign in to SparkVault and open [Integrations](https://app.sparkvault.com/integrations)
2.  Select **HubSpot** and click **Connect HubSpot**
3.  Authorize the requested permissions in HubSpot and choose your portal
4.  Back in SparkVault, choose the vault where CRM files will be stored
5.  SparkVault verifies your ownership of the selected vault and confirms the installation

> **Installation Invariants**
>
> Each SparkVault account can have **one active HubSpot installation**, and a HubSpot portal can be bound to **at most one SparkVault account**. The vault you select in the dashboard is verified on the server with your own credentials; an installation can never bind to a vault you don't own (`Vault not found or access denied`).

### Requested HubSpot OAuth Scopes

| Scope | Purpose |
| --- | --- |
| `oauth` | OAuth token exchange and identifying the connected portal |
| `crm.objects.contacts.read` | Record context for the Files card on Contact records |
| `crm.objects.companies.read` | Record context for the Files card on Company records |
| `crm.objects.deals.read` | Record context for the Files card on Deal records |
| `tickets` | Record context for the Files card on Ticket records |

### Add the Card in HubSpot

After connecting, add the SparkVault Files card to your record layouts:

1.  Open any Contact, Company, Deal, or Ticket in HubSpot
2.  Click **Customize** in the top-right of the record page
3.  In the sidebar section, click **\+ Add card** and select **SparkVault Files**
4.  Click **Save**; the card now appears on all records of that type
5.  Enter your Vault Master Key (VMK) or DVAK to unseal and start uploading files

[Connect HubSpot](https://app.sparkvault.com/integrations)

## Using the Files Card

The card has two states. While the vault is **sealed**, it prompts for your Vault Master Key (VMK) or a Device Vault Access Key (DVAK). Once **unsealed**, the card shows the encrypted files attached to the record you are viewing:

-   **List**: The card shows only the files in the viewed record's folder, never the rest of the vault.
-   **Upload**: Uploads open the SparkVault vault view embedded in HubSpot, scoped to the record's folder. File bytes are encrypted and travel directly between your browser and Forge.
-   **Download**: Downloads open a signed, short-lived Forge URL in an embedded download window: the decrypted stream goes directly from Forge to your browser, never through HubSpot.
-   **Delete**: Removes a file from the record's folder. Deletion is scoped to the record you are viewing.

> **Reconnect Prompt**
>
> If the stored SparkVault connection behind the installation expires or is revoked, the card shows a reconnect prompt instead of an error. Reconnect from [Integrations](https://app.sparkvault.com/integrations) to restore it.

## Security Model

-   **Triple Zero-Trust encryption via Forge**: Files are encrypted with AES-256-GCM using keys derived from your vault's key hierarchy. Once the vault is sealed, only your Vault Master Key can unlock them; SparkVault employees cannot read your files.
-   **File bytes never transit HubSpot**: Uploads and downloads move directly between your browser and Forge. HubSpot only renders the card and relays signed control requests.
-   **HubSpot v3 request signatures**: Every request the card makes to SparkVault is signed by HubSpot with the app's client secret (HMAC-SHA256 over method, URI, body, and timestamp) via the `X-HubSpot-Signature-v3` and `X-HubSpot-Request-Timestamp` headers. Requests older than five minutes are rejected, and signatures are compared in constant time. The signature, not the portal ID, is the caller proof.
-   **Per-user unseal sessions**: Unsealing mints a vault access token stored for the verified HubSpot user who entered the key, valid for one hour. Other users in the portal must unseal themselves.
-   **Per-record authorization**: Downloads and deletions verify the requested file actually lives in the viewed record's folder. A file ID from elsewhere in the vault is rejected, enforcing isolation between records even within your own portal.
-   **Vault ownership verified at install**: The OAuth callback re-checks the selected vault with the installing user's own credentials, so an installation can never be bound to a vault the installer doesn't own.
-   **Audit trail**: Every operation runs through the SparkVault Core API and is recorded in the unified audit log.

## API Endpoints

The HubSpot integration is driven entirely from HubSpot's UI; there is no customer-facing file API surface specific to this integration. The one endpoint you can call directly is uninstall.

#### `DELETE /v1/apps/hubspot/uninstall`

Disconnect HubSpot from your SparkVault account. Removes the installation and its stored OAuth connection. Requires standard SparkVault authentication.

```bash
curl -X DELETE https://api.sparkvault.com/v1/apps/hubspot/uninstall \
  -H "Authorization: Bearer YOUR_SESSION_JWT"
```

```json
{
  "data": {
    "uninstalled": true,
    "account_id": "acc_a1b2c3d4",
    "portal_id": "244567890"
  },
  "meta": {
    "api_version": "1.2.828",
    "response_ms": 84,
    "request_id": "3f9d2b7c-8a1e-4c5b-9d0f-6e2a4b8c1d3e",
    "timestamp": 1782864000
  }
}
```

> **Authentication**
>
> This endpoint uses standard SparkVault authentication: a session JWT (`Authorization: Bearer …`) or an API key (`X-API-Key`).

> **Uninstall Behavior**
>
> Uninstalling removes the OAuth connection between SparkVault and your HubSpot portal; the SparkVault Files card stops working on CRM records. **Your files are not deleted**: they remain encrypted in your vault and stay accessible from the SparkVault app. Removing the app from the HubSpot side instead triggers the same cleanup via the `app.deauthorize` webhook. Reinstalling requires running the OAuth flow again.

#### Error Responses

| Status | Code | Description |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | HubSpot is not installed for this account. |
| 401 | `AUTHENTICATION_ERROR` | Missing or invalid session JWT. |

## Integration Endpoints (Internal)

The following endpoints are called by HubSpot's servers (as signed `hubspot.fetch()` requests from the Files card) or by the SparkVault dashboard during installation. They are documented for transparency and should not be called directly by your application.

| Endpoint | Purpose | Auth |
| --- | --- | --- |
| `POST /v1/apps/hubspot/resolve` | Maps a CRM record to its vault and folder so the card can render | HubSpot v3 signature |
| `POST /v1/apps/hubspot/files` | Lists the encrypted files for the record being viewed | HubSpot v3 signature |
| `POST /v1/apps/hubspot/unseal` | Unseals the vault with the VMK or DVAK entered in the card | HubSpot v3 signature |
| `POST /v1/apps/hubspot/download` | Issues a signed Forge URL for a file on the viewed record | HubSpot v3 signature |
| `POST /v1/apps/hubspot/delete-file` | Deletes a file from the viewed record's folder | HubSpot v3 signature |
| `POST /v1/apps/hubspot/oauth/callback` | OAuth code exchange and vault binding during installation | SparkVault session JWT |
| `POST /v1/apps/hubspot/webhooks` | HubSpot lifecycle events (`app.deauthorize`) | HubSpot v3 signature |

> **Signature Verification**
>
> All proxy and webhook requests are verified with HubSpot's v3 request signature: an HMAC-SHA256 of the method, full URI, raw body, and timestamp, keyed with the app's client secret. This proves requests originate from HubSpot on behalf of a signed-in portal user, not from an arbitrary caller who knows a portal ID.

## Pricing

The HubSpot integration is **free to install**. Files stored through the integration are billed exactly like files uploaded in the SparkVault app; standard vault storage and transfer pricing applies. There is no per-operation charge for the integration itself.

## Get Started

Connect HubSpot and bring encrypted file storage to every record in your CRM.

[Connect HubSpot](https://app.sparkvault.com/integrations) [Learn About Vaults](/api/docs/vaults/)