Skip to main content

Vault

The vault stores signed documents as tamper-evident authoritative copies per UCC §9-105. Partners access vaulted artifacts through short-lived signed URLs — no PIN, session, or interactive custody flow is required from the partner side.

Documents must be vaulted first

These endpoints only return data once an envelope has been vaulted. Vaulting does not happen automatically on completion — an admin or custodian must trigger it via POST /api/v2/partner/envelopes/:id/vault-in-signed (e-sign) or /vault-in-upload (paper). Calling these endpoints on a completed-but-not-vaulted envelope returns 404.

All partner vault endpoints are authenticated with X-API-Key: lk_... and return { "data": ... }. Signed URLs expire after 5 minutes by default; pass ?expires=<seconds> (60–86400) to override.

Download authoritative copy​

GET /partner/envelopes/:id/vault/signed-url

Required scope: vault:read

Returns a short-lived signed URL that streams the authoritative PDF (default 5 minutes; override with ?expires=<seconds>).

{
  "data": {
    "signed_url": "https://storage.stg.loyva.net/ucc-vault/...?token=...",
    "filename": "env_x7k9m2p4q1w3_authoritative.pdf",
    "expires_in": 3600,
    "expires_at": "2026-04-11T11:00:00.000Z"
  }
}

The authoritative copy download verifies the SHA-256 hash on the way out. If the re-computed hash does not match the stored document_hash, the download is denied and a tamper event is recorded.

Download backup copy​

GET /partner/envelopes/:id/vault/copy/signed-url

Required scope: vault:read

Returns a signed URL for the non-authoritative duplicate of the signed document. Use this for day-to-day viewing and distribution so the authoritative copy's access log stays clean.

{
  "data": {
    "signed_url": "https://storage.stg.loyva.net/ucc-copies/...?token=...",
    "filename": "env_x7k9m2p4q1w3_copy.pdf",
    "expires_in": 3600,
    "expires_at": "2026-04-11T11:00:00.000Z"
  }
}

Get compliance certificate​

GET /partner/envelopes/:id/vault/certificate

Required scope: compliance:read

Returns the full UCC §9-105 compliance certificate JSON for a vaulted envelope. See UCC overview for the complete shape.

{
  "data": {
    "certificate_type": "ucc_9105_electronic_chattel_paper",
    "certificate_version": "1.0",
    "issued_at": "2026-04-11T10:16:05.000Z",
    "subject": {
      "envelope_id": "env_x7k9m2p4q1w3",
      "envelope_name": "Q1 Sales Agreement",
      "customer_id": "cust_abc123",
      "status": "vaulted"
    },
    "secured_party": { "name": "First National Bank", "role": "secured_party" },
    "document_integrity": {
      "hash_algorithm": "SHA-256",
      "document_hash": "a1b2c3d4..."
    },
    "ucc_9105_compliance": { "compliant": true, "score": 100, "checks": [ /* 8 checks */ ] },
    "esign_act_compliance": { "act": "ESIGN", "citation": "15 U.S.C. §7001", "compliant": true }
  }
}

Returns 404 if the certificate has not yet been generated (the vault pipeline is still processing or failed).

Vault integrity guarantees​

PropertyValue
Hash algorithmSHA-256
Single-copy enforcementOne authoritative copy per envelope
Integrity verificationHash verified on every authoritative-copy download
Prior-version retentionEvery replacement is archived (UCC §9-105(b)(4))
Scheduled integrity checksWeekly re-hash of every vaulted document