API Documentation

API Overview

The SecLink API allows developers and automation tools to programmatically create and securely distribute self-destructing secrets. The API handles the storage and retrieval lifecycle, while your client code must handle the AES-256-GCM encryption.

Authentication

Accessing the API requires an API key, passed in the Authorization header as a Bearer token.

Authorization: Bearer sk_live_your_api_key_here

Note: API keys are available in our Pro tier ($9/month).

Rate Limits

Free unauthenticated endpoints are limited to 20 requests per hour. Paid API keys have customized limits starting at 10,000 requests per hour.

Endpoints

Create a Secret

POST /api/v1/secrets

Submit an already-encrypted secret blob to the server.

{
  "encryptedBlob": "base64_encoded_string",
  "iv": "base64_encoded_string",
  "expiryType": "view_once" | "1hour" | "24hours" | "7days",
  "passcodeHash": "optional_sha256_hash"
}

Response:

{
  "linkId": "A1b2C3d4E5f6",
  "shareUrl": "https://seclink.local/A1b2C3d4E5f6",
  "expiresAt": 1716172000000
}

Retrieve a Secret

GET /api/v1/secrets/:id

Fetch the encrypted blob. If the secret is set to view_once, this request will instantly permanently delete the secret from the server.

{
  "encryptedBlob": "base64_encoded_string",
  "iv": "base64_encoded_string",
  "expiryType": "view_once"
}

Report Abuse

POST /api/v1/secrets/:id/report

Report a link ID for terms of service violations.

Error Codes

• 400 Bad Request: Invalid payload or missing fields.
• 401 Unauthorized: Invalid API key or wrong passcode.
• 404 Not Found: Secret does not exist or has already been viewed.
• 410 Gone: Secret was previously viewed and permanently destroyed.
• 429 Too Many Requests: You have exceeded your rate limit.
• 500 Internal Error: Server encountered a problem.

Code Examples

cURL

curl -X POST https://seclink.local/api/v1/secrets \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"encryptedBlob":"...","iv":"...","expiryType":"view_once"}'

JavaScript (Fetch)

const response = await fetch('https://seclink.local/api/v1/secrets', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    encryptedBlob: btoa('encrypted_data'),
    iv: btoa('initialization_vector'),
    expiryType: 'view_once'
  })
});
const data = await response.json();

Python (Requests)

import requests

response = requests.post(
    'https://seclink.local/api/v1/secrets',
    headers={
        'Authorization': 'Bearer sk_live_xxx',
        'Content-Type': 'application/json'
    },
    json={
        'encryptedBlob': '...',
        'iv': '...',
        'expiryType': 'view_once'
    }
)
print(response.json())