API Documentation

Create encrypted secrets programmatically with our REST API. Zero-knowledge encryption — your secrets and passwords never reach our servers.

How Recipients Get the Unlock Password

The unlock password is never sent to our API. You must share it separately with the recipient through a secure channel (e.g., WhatsApp, Signal, in person). Our API only stores the encrypted blob — we cannot and do not handle password delivery.

Your responsibility: When you create a secret via API, you must share (1) the secret URL and (2) the unlock password with the recipient through two different channels for security.

Authentication

Use an API token to authenticate. Create tokens in your Dashboard. Send the token in the Authorization header:

Authorization: Bearer enigma_xxxxxxxxxxxxxxxx

Without a valid token, requests use anonymous rate limits and may require reCAPTCHA.

POST /api/messages — Create a Secret

Creates an encrypted secret. You must encrypt the content client-side before sending. We never accept plaintext.

Request Body

{
  "encryptedContent": "string (REQUIRED) - pre-encrypted blob",
  "name": "string (optional)",
  "expiresAt": "ISO8601 or null (optional)",
  "maxAccess": number or null (optional)
}

Response (201)

{
  "success": true,
  "message": "Message stored successfully",
  "data": {
    "messageId": "a8Kx9pQ2",
    "deleteToken": "xxx (only for anonymous secrets)"
  }
}

Example (cURL)

curl -X POST https://enigmacrypt.app/api/messages \
  -H "Authorization: Bearer enigma_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "encryptedContent": "<your-pre-encrypted-blob>",
    "name": "API Secret",
    "expiresAt": null,
    "maxAccess": 1
  }'

Client-Side Encryption (Required)

You must encrypt your secret locally before sending it to the API. Our server only accepts pre-encrypted content.

Algorithm

AES-256-CBC
PBKDF2 key derivation, 100,000 iterations
Random salt (16 bytes) + random IV (16 bytes) prepended to ciphertext

Format

Output = salt (hex) + iv (hex) + base64(ciphertext). Salt and IV are 32 hex chars each.

Message object before encryption: { version: "v1", content: "your-secret", created: "ISO8601" }

See integration examples below for complete code in Node.js, Python, Go, and cURL.

Ejemplos de integración

Código completo para cifrar y enviar secretos a la API en distintos lenguajes.

const CryptoJS = require("crypto-js")

function encryptMessage(message, key) {
  const salt = CryptoJS.lib.WordArray.random(128 / 8)
  const derivedKey = CryptoJS.PBKDF2(key, salt, {
    keySize: 256 / 32,
    iterations: 100000,
  })
  const iv = CryptoJS.lib.WordArray.random(128 / 8)
  const messageObj = {
    version: "v1",
    content: message,
    created: new Date().toISOString(),
  }
  const encrypted = CryptoJS.AES.encrypt(
    JSON.stringify(messageObj),
    derivedKey,
    { iv, padding: CryptoJS.pad.Pkcs7, mode: CryptoJS.mode.CBC }
  )
  return salt.toString() + iv.toString() + encrypted.toString()
}

async function createSecret(secret, password, apiToken) {
  const encryptedContent = encryptMessage(secret, password)
  const res = await fetch("https://enigmacrypt.app/api/messages", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      encryptedContent,
      name: "API Secret",
      expiresAt: null,
      maxAccess: 1,
    }),
  })
  const data = await res.json()
  if (!data.success) throw new Error(data.error)
  return { url: `https://enigmacrypt.app/s/${data.data.messageId}`, password }
}

Rate Limits

Limits are per identifier (IP or API token). Exceeding returns 429.

Anonymous (no token): 20 requests per 15 minutes
With API token: 100 requests per 15 minutes