Messaging v1

Overview

SparkVault Messaging gives your business durable, two-way encrypted conversations with people who do not have a SparkVault account. A customer is invited to a thread, verifies themselves once through SparkVault Identity, and can then read and reply from any device. Every message your business sends carries a cryptographic receipt of record that a third party can independently verify.

Message content lives only as vault ingots: one immutable, VAK-sealed Forge ingot per message. It is never stored in DynamoDB and never in raw S3. Reads are server-mediated: the server brokers a single-use key, decrypts the requested ingot, and returns plaintext to an authorized participant.

What You Get

• Account-less recipients: invite anyone by email or phone; they verify through SparkVault Identity and become a stable participant.
• Receipts of record: every send is attested to the account audit trail and can be exported as a portable, JWKS-verifiable token.
• Compliance controls: per-conversation retention, recall, legal hold, per-participant opt-out, and an immutable audit log of metadata.
• Attachments: client-direct upload/download of files up to 100 MB, each sealed as its own conversation-tagged ingot.

Data Model

A conversation is an index-only manifest plus a set of content-addressable ingots. Understanding the four core objects makes the endpoints below self-explanatory.

Manifest, Not Mailbox

The manifest (messaging-conversations) is an index only: an atomic message-id counter, committed_through (the highest contiguous durable id, the sole authority for what a reader fetches), compacted_through, the participant roster, settings, a 25-entry recent window, the recalled tombstone list, the legal_hold flag, and the closed flag. A participant's last-read position is last_read_id on their per-user inbox row; there are no per-message read receipts.

Vault & Encryption

Each account has one system-flagged "messaging" vault that holds every conversation's ingots, not a vault per conversation. Conversations are isolated by their deterministic ingot ids plus a membership check, not by separate keys.

• The vault's master key (VMK) is generated once and held only via a system messaging DVAK (Delegated Vault Access Key).
• All messaging crypto is server-brokered through that DVAK (resolveMessagingVak) for owner and recipient alike. The raw VAK never leaves the server; Forge receives single-use ISTKs.
• This is the mechanism for posture S. Triple zero-trust at rest is unchanged: content is sealed, and reads decrypt only transiently for an authorized participant.

Authentication

Messaging has two access surfaces, each authenticated differently.

Business Side

Your application calls the authenticated Core routes under /v1/products/messaging/* using a SparkVault API key or a user JWT. The authenticated principal is the conversation participant.

Account-less Recipient

A recipient with no SparkVault account authenticates as an OIDC relying party to auth.sv using the PKCE authorization-code flow against the company account's Identity tenant. They never hold an API key. The verified id_token is their bearer credential on the public /m/* routes.

Business-Side Endpoints

Base URL: https://api.sparkvault.com/v1/products/messaging

All paths below are authenticated with an API key or user JWT. Owner-only operations are noted; every operation re-checks conversation membership.

Inbox

Create Conversation

Get Conversation

Send Message

curl -X POST 'https://api.sparkvault.com/v1/products/messaging/conversations/cnv_019aec85fe5972b3c4d5e6f7a8b9c0d1/messages' \
  -H 'Authorization: Bearer YOUR_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "Your wire transfer was received. Reference #SV-4471.",
    "content_type": "text/plain"
  }'

{
  "message_id": 42,
  "conversation_id": "cnv_019aec85fe5972b3c4d5e6f7a8b9c0d1",
  "ts": 1703977200,
  "ingot_id": "ing_8f1c2d4a6b9e0c5f3a7d1e2b4c6f8a09",
  "content_hash": "9b3e7c1a5f8d2e0b4a6c8f1d3e5b7a9c2d4f6e8a0b1c3d5e7f9a1b3c5d7e9f0a",
  "committed_through": 42,
  "status": "committed",
  "receipt": {
    "account_id": "acc_example",
    "conversation_id": "cnv_019aec85fe5972b3c4d5e6f7a8b9c0d1",
    "message_id": 42,
    "sender_svid": "ing_019e66a4e27875f2822ede0e4f5d8792",
    "content_hash": "9b3e7c1a5f8d2e0b4a6c8f1d3e5b7a9c2d4f6e8a0b1c3d5e7f9a1b3c5d7e9f0a",
    "ts": 1703977200
  }
}

Read Messages

A from_id..to_id range spans at most 50 messages (2 pages). A larger range is rejected with 400 ("Read range too large (max 50 messages); paginate"). Without a range, the newest page returns up to 25 messages.

{
  "messages": [
    {
      "schema_version": 1,
      "message_id": 41,
      "sender_svid": "mid_7c2a9f4b1d8e3a05f6e4d2c0b8a69753",
      "sender_identity": { "type": "email", "account_less": true },
      "ts": 1703970000,
      "content_type": "text/plain",
      "content": "Can you confirm the routing number?",
      "attachments": []
    },
    { "message_id": 40, "recalled": true }
  ],
  "committed_through": 42,
  "compacted_through": 25
}

Recall Message

Fetch Receipt Token

The token is re-derived from the immutable message: its content_hash is re-hashed from the sealed bytes (never caller-supplied), and that hash is also set as the token's action_hash. A verifier holding the message content can recompute the hash and confirm the token attests this exact message, the same action_hash binding the SparkVault SDK uses (verifyIdToken with expectedActionHash). The token's exp tracks settings.audit_retention_seconds, so a receipt verifies for as long as the company retains the record.

curl 'https://api.sparkvault.com/v1/products/messaging/conversations/cnv_019aec85fe5972b3c4d5e6f7a8b9c0d1/messages/42/receipt' \
  -H 'Authorization: Bearer YOUR_JWT'

{
  "receipt_token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "expires_at": 1711753200,
  "receipt": {
    "account_id": "acc_example",
    "conversation_id": "cnv_019aec85fe5972b3c4d5e6f7a8b9c0d1",
    "message_id": 42,
    "sender_svid": "ing_019e66a4e27875f2822ede0e4f5d8792",
    "content_hash": "9b3e7c1a5f8d2e0b4a6c8f1d3e5b7a9c2d4f6e8a0b1c3d5e7f9a1b3c5d7e9f0a",
    "message_ts": 1703977200
  }
}

{
  "iss": "https://auth.sparkvault.com/acc_example",
  "sub": "ing_019e66a4e27875f2822ede0e4f5d8792",
  "aud": "acc_example",
  "jti": "b1f0c2d3-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "token_type": "messaging_receipt",
  "conversation_id": "cnv_019aec85fe5972b3c4d5e6f7a8b9c0d1",
  "message_id": 42,
  "content_hash": "9b3e7c1a5f8d2e0b4a6c8f1d3e5b7a9c2d4f6e8a0b1c3d5e7f9a1b3c5d7e9f0a",
  "message_ts": 1703977200,
  "svid": "ing_019e66a4e27875f2822ede0e4f5d8792",
  "action_hash": "9b3e7c1a5f8d2e0b4a6c8f1d3e5b7a9c2d4f6e8a0b1c3d5e7f9a1b3c5d7e9f0a",
  "iat": 1703977200,
  "exp": 1711753200
}

Participants

Invite Account-less Recipient

Attachments

Read, Archive & Opt-out

Legal Hold & Close (Owner)

Account-less Recipient Routes

The public /m/* routes mirror the business-side surface for a verified recipient. They are gated by the auth.sv id_token (presented as Authorization: Bearer or x-messaging-token), and the META membership check is re-run on every operation. Identifiers are redacted so one recipient never sees another's email or phone.

Governance & Compliance

Messaging is built for regulated, auditable business-to-customer communication. Every governance control is per-conversation and re-checked on the relevant operation.

Alerts

Alerts notify the other, non-opted-out participants of new activity. They carry metadata only, never content.

• Real-time nudge: a best-effort WebSocket notification (reusing the Notify connection registry) when a message lands, conversation and message id only; the client fetches content through the read path.
• Invite email: a single transactional email delivering the access link when a recipient is invited by email (best-effort). Phone invites return the access_url for your application to deliver.

Billing

Messaging bills two dimensions, both automatic. There is no per-message or per-transaction billing.

Error Responses

Messaging uses the standard SparkVault error envelope: { error: { code, message, details } }. Common failures:

Get Started

Messaging shares SparkVault's API authentication and Identity verification. To integrate:

1. Create an API key on the API Keys page.
2. Create a conversation, then invite a recipient by email or phone.
3. Send messages and fetch receipts as shown above.
4. For verifiable proof, export a receipt token and validate it against the Identity JWKS.