Developer Platform

VanishShare API & CLI Reference

Integrate zero-knowledge secret sharing into CI/CD pipelines, DevOps automation scripts, and custom internal tools.

🔒 Zero-Knowledge API Architecture Notice

VanishShare enforces client-side zero-knowledge security. The API endpoints accept only ciphertext. Clients must generate a 256-bit AES key locally, encrypt the secret text or binary file, and append the key strictly into the URL hash fragment (#key=...). The server never receives or stores raw decryption keys.

Terminal CLI (npm)

Share credentials or files directly from your terminal with the vanishshare npm package. It encrypts on your machine and sends only ciphertext. A raw curl call cannot do this, so do not post secrets to the API with curl.

# Prompt for the secret (input is hidden):
npx vanishshare --recipient teammate@company.com

# Or pipe it in on stdin:
printf %s "$DB_PASSWORD" | npx vanishshare --recipient teammate@company.com

# Share an encrypted file (up to 200KB), expiring after 1 day:
npx vanishshare --file ./credentials.json --ttl 86400 --recipient teammate@company.com

Do not pass the secret as a command-line argument: arguments end up in your shell history and are visible to other local users in ps. Run npx vanishshare --help for all options.

REST API Endpoints

Base URL: https://vanishshare.app/api

POST/api/secrets

Upload an encrypted ciphertext payload with custom TTL and download limitations.

// Request Payload (JSON)
{
  "encryptedText": "{\"ciphertext\": \"...\", \"iv\": \"...\"}", // Optional JSON string
  "encryptedFile": "...",                     // Optional base64 encoded ciphertext
  "encryptedFileMetadata": "...",             // Optional encrypted JSON metadata
  "hasPassphrase": false,                     // boolean
  "recipientEmails": ["dev@example.com"],     // Array of authorized recipient emails
  "ttl": 86400,                               // Expiration in seconds (e.g. 600, 86400)
  "maxDownloadTimes": 1,                      // Integer or -1 for unlimited
  "salt": "..."                               // Cryptographic salt if passphrase is used
}

// Response (200 OK)
{
  "id": "abc-123-uuid",
  "expiresAt": "2026-09-27T10:00:00.000Z"
}
GET/api/secrets/:id

Query secret metadata before verification. Returns whether passphrase or OTP is needed.

// Response (200 OK)
{
  "id": "abc-123-uuid",
  "hasPassphrase": true,
  "salt": "d98127398127...",
  "maxDownloadTimes": 1,
  "downloadCount": 0,
  "expiresAt": "2026-09-27T10:00:00.000Z"
}
POST/api/secrets/:id/otp

Dispatch a 6-digit one-time passcode to an authorized recipient email address.

// Request
{
  "email": "dev@example.com"
}

// Response (200 OK)
{
  "message": "Verification code has been sent to your email."
}
POST/api/secrets/:id/verify

Submit OTP and retrieve the encrypted ciphertext payloads. Increments the download counter.

// Request
{
  "email": "dev@example.com",
  "otp": "582914"
}

// Response (200 OK)
{
  "encryptedText": "{\"ciphertext\": \"...\", \"iv\": \"...\"}",
  "encryptedFile": "...",
  "encryptedFileMetadata": "..."
}

TypeScript / Node.js Web Crypto Integration

Encrypting data client-side before calling the API:

import { webcrypto } from "crypto";

async function createSecret(secretText: string) {
  // 1. Generate 256-bit AES-GCM Key
  const key = await webcrypto.subtle.generateKey(
    { name: "AES-GCM", length: 256 },
    true,
    ["encrypt", "decrypt"]
  );

  // 2. Encrypt text locally
  const iv = webcrypto.getRandomValues(new Uint8Array(12));
  const encoded = new TextEncoder().encode(secretText);
  const ciphertextBuffer = await webcrypto.subtle.encrypt(
    { name: "AES-GCM", iv },
    key,
    encoded
  );

  const ciphertextBase64 = Buffer.from(ciphertextBuffer).toString("base64");
  const ivBase64 = Buffer.from(iv).toString("base64");

  // 3. Post to VanishShare API
  const res = await fetch("https://vanishshare.app/api/secrets", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      encryptedText: JSON.stringify({ ciphertext: ciphertextBase64, iv: ivBase64 }),
      ttl: 86400,
      maxDownloadTimes: 1,
    }),
  });

  const { id } = await res.json();
  const rawKey = await webcrypto.subtle.exportKey("raw", key);
  const keyBase64 = Buffer.from(rawKey).toString("base64");

  // The decryption key is appended to the hash fragment (#)
  return `https://vanishshare.app/share/${id}#key=${encodeURIComponent(keyBase64)}`;
}

Ready to Start Sharing Secrets?

Use our web interface or build custom integrations with our zero-knowledge API.

Go to Web Interface