Burn the Secret API

Documentation

The Burn the Secret API allows you to programmatically create, retrieve, and manage self-destructing secrets. Use it to securely share passwords, API keys, and sensitive information in your applications.

Overview

Burn the Secret is a secure secret-sharing service that encrypts sensitive information and generates self-destructing links. Secrets are automatically deleted after they expire or reach their view limit.

Base URL: https://burnthesecret.com/api

Content Type: All requests must use application/json

Key Features

Auto-expiring links — Set TTL from 30 minutes to 999 days
View limits — Secrets auto-delete after a set number of views
Password protection — Optional passphrase for extra security
File support — Share files up to 50MB
Burn on demand — Manually delete secrets at any time

How It Works

1. Create a secret — Send your sensitive content to the API with optional settings like TTL, view limit, and passphrase.

2. Get the secure link — The API returns a unique URL that you can share with your recipient.

3. Recipient views the secret — When they open the link, the secret is decrypted and displayed. This counts as a view.

4. Auto-destruct — Once the view limit is reached or the TTL expires, the secret is permanently deleted from our servers.

Authentication

Authentication is optional. You can create secrets without any API key—sending a key only links the secret to your account. To attribute a secret, include your key in theAuthorizationheader:

HTTP Header

Authorization: Bearer ks_live_your_api_key

Get your API key from the API Access page in your dashboard. Omit the header and the request is still accepted (anonymous, or linked to your signed-in browser session). Only if you send a key that is invalid or revoked is the request rejected—with 401 INVALID_API_KEY. Keep your API key secure and never expose it in client-side code.

Create Secret

Create a new encrypted secret with customizable expiration and view limits.

POST /api/secrets

Example Request

cURL

curl -X POST https://burnthesecret.com/api/secrets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ks_live_your_api_key" \
  -d '{
    "secret": "my-super-secret-password",
    "ttl": 86400,
    "maxViews": 1,
    "passphrase": "optional-password"
  }'

Example Response

JSON

{
  "success": true,
  "metadata": {
    "key": "abc123xyz",
    "secretKey": "def456uvw",
    "ttl": 86400,
    "expiresAt": "2025-01-27T12:00:00.000Z",
    "createdAt": "2025-01-26T12:00:00.000Z",
    "hasPassphrase": true,
    "hasText": true,
    "fileCount": 0,
    "maxViews": 1,
    "viewCount": 0,
    "serverEncrypted": true
  },
  "secretUrl": "https://burnthesecret.com/secret/def456uvw#key=Zm9vYmFy...",
  "metadataUrl": "https://burnthesecret.com/receipt/abc123xyz",
  "requestId": "req_m4k7x2_abc123"
}

JavaScript

const response = await fetch('https://burnthesecret.com/api/secrets', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ks_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    secret: 'my-sensitive-data',
    ttl: 86400,
    maxViews: 1,
  }),
});

const data = await response.json();
console.log(data.secretUrl);

Python

import requests

response = requests.post(
    'https://burnthesecret.com/api/secrets',
    headers={
        'Authorization': 'Bearer ks_live_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'secret': 'my-sensitive-data',
        'ttl': 86400,
        'maxViews': 1,
    }
)

data = response.json()
print(data['secretUrl'])

Understanding Key Types

When you create a secret, the API returns two different keys. Understanding the difference is important:

secretKey

Used by recipients to view the secret content. Share this key (via the secretUrl) with the person who needs to see the secret. Viewing with this key increments the view count.

metadataKey (key)

Used by the sender to check status or delete the secret. This is your "receipt" - use it to see if the secret was viewed, or to burn it before the recipient sees it.

Get Secret Status

Check the status of a secret without viewing its content. Works with either key type.

GET /api/secrets/:key

Example Request

cURL

curl https://burnthesecret.com/api/secrets/abc123xyz

Example Response

JSON

{
  "exists": true,
  "type": "metadata",
  "viewed": false,
  "burned": false,
  "expiresAt": "2025-01-27T12:00:00.000Z",
  "hasPassphrase": true,
  "secretKey": "def456uvw",
  "maxViews": 1,
  "viewCount": 0,
  "viewsRemaining": 1,
  "requestId": "req_m4k9z4_ghi789"
}

Note: This endpoint does not count as a view and does not reveal the secret content.

View Secret Content

Retrieve and view a secret's content. This increments the view count and may trigger deletion if the view limit is reached. Use the secretKey (not the metadataKey).

POST /api/secrets/:secretKey

Request Body

Parameter	Type	Description
passphrase	string	Required if the secret is password-protected

Example Request

cURL

curl -X POST https://burnthesecret.com/api/secrets/def456uvw \
  -H "Content-Type: application/json" \
  -d '{"passphrase": "optional-password"}'

Example Response

JSON

{
  "success": true,
  "text": {
    "ciphertext": "base64-encoded-ciphertext...",
    "iv": "base64-encoded-iv..."
  },
  "files": [],
  "oneClickRetrieval": true,
  "viewsRemaining": 0,
  "requestId": "req_m4k8y3_def456"
}

The API returns the encrypted text as { ciphertext, iv }, never a decrypted plaintext value. Decrypt it client-side using the key from the URL fragment (the part after #).

Delete Secret

Permanently delete (burn) a secret before it expires. You can burn with either the metadata key or the secret key. If the sender disabled deletion, burning with the secret key returns403 DELETION_NOT_ALLOWED.

DELETE /api/secrets/:key

Example Request

cURL

curl -X DELETE https://burnthesecret.com/api/secrets/abc123xyz

Example Response

JSON

{
  "success": true,
  "message": "Secret burned successfully",
  "requestId": "req_m4kaz5_jkl012"
}

Request Parameters

Parameters for the Create Secret endpoint.

Parameter	Type	Required	Description
secret	string	Yes	The content to encrypt (max 50MB)
ttl	integer	No	Time to live in whole seconds. Min: 1800 (30 min), Max: 86400000 (999 days). Default: 86400 (1 day)
maxViews	integer \| null	No	Max views before deletion. 1-999, or null for unlimited. Default: 1
passphrase	string	No	Raw passphrase, 4-256 chars (sent over HTTPS; hashed server-side). If set, required to view the secret
oneClickRetrieval	boolean	No	Require click to reveal content. Default: true
allowDeletion	boolean	No	Allow recipient to delete after viewing. Default: true

Error Handling

All error responses follow a consistent format with an error code and helpful hint:

JSON

{
  "error": "Invalid passphrase",
  "code": "INVALID_PASSPHRASE",
  "hint": "The secret is password-protected. Include the correct 'passphrase' in your request body.",
  "requestId": "req_m4kbz6_mno345"
}

HTTP Status Codes

Status	Meaning	Description
200	OK	Request succeeded
400	Bad Request	Invalid or missing parameters
401	Unauthorized	API key sent but invalid or revoked (a key is optional)
403	Forbidden	Invalid passphrase, or burn blocked because the sender disabled deletion
404	Not Found	Secret not found, expired, or already viewed
410	Gone	Secret burned, expired, or max views reached
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

Error Codes

Code	Description
INVALID_KEY	Key format is invalid (must be alphanumeric)
INVALID_JSON	Request body is not valid JSON
INVALID_API_KEY	API key was sent but is invalid or revoked (a key is optional)
MISSING_CONTENT	No secret content (text, secret, or files) provided in request
CONTENT_TOO_LARGE	Secret exceeds the 50 MB size limit
NOT_FOUND	Secret doesn't exist or has been deleted
INVALID_PASSPHRASE	Wrong passphrase for protected secret
SECRET_BURNED	Secret was manually deleted by sender
SECRET_EXPIRED	Secret has passed its expiration time
MAX_VIEWS_REACHED	Secret has reached maximum view count
RATE_LIMIT_EXCEEDED	Too many requests, check Retry-After header
INTERNAL_ERROR	Server error, contact support if persistent

Rate Limits

API requests are rate-limited per IP address on a sliding window. The limits below apply uniformly to every request—anonymous, signed in, or using an API key. There are no per-tier limits.

Resource	Limit
Max content size	50 MB total
Max TTL	999 days
Max view limit	999 (or unlimited with null)
Max files per secret	20

Rate Limit Headers

All API responses include rate limit headers:

X-RateLimit-Limit — Maximum requests allowed
X-RateLimit-Remaining — Requests remaining in current window
X-RateLimit-Reset — Unix timestamp when the limit resets
X-Request-Id — Unique request identifier for debugging

When rate limited, responses include a Retry-After header with seconds until reset.

Ready to get started?

Create your API key and start integrating Burn the Secret into your applications.

Get API Key