Skip to content

api.md

Latest commit

 

History

History
106 lines (79 loc) · 4.32 KB

api.md

File metadata and controls

106 lines (79 loc) · 4.32 KB

API Documentation

Hemmelig provides a REST API for programmatic access to secret sharing functionality.

Interactive Documentation

The API is documented using OpenAPI 3.0 specification with an interactive Swagger UI:

  • Swagger UI: /api/docs - Interactive API explorer
  • OpenAPI Spec: /api/openapi.json - Raw OpenAPI specification

Authentication

Session Authentication

For browser-based access, authenticate through the /auth endpoints provided by better-auth. Session cookies are automatically managed.

API Key Authentication

For programmatic access, create an API key in your account settings under the Developer tab.

Use the API key as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer hemmelig_your_api_key_here" \
  https://your-instance.com/api/secrets

Important:

  • API keys are shown only once upon creation - store them securely
  • Maximum 5 API keys per user
  • Keys can optionally expire after 30, 90, or 365 days
  • Revoke compromised keys immediately from your account settings

For endpoints requiring admin access, the authenticated user must have the admin role.

Quick Reference

Public Endpoints

Method Endpoint Description
GET /api/healthz Health check
POST /api/secrets Create a new secret
POST /api/secrets/:id Retrieve a secret (password in body if protected)
GET /api/secrets/:id/check Check if secret exists and requires password
POST /api/files Upload a file
GET /api/files/:id Download a file
GET /api/instance/settings/public Get public instance settings
GET /api/setup/status Check if initial setup is needed
POST /api/setup/complete Complete initial setup

Authenticated Endpoints

Method Endpoint Description
GET /api/secrets List user's secrets
DELETE /api/secrets/:id Delete a secret
GET /api/account Get account info
PUT /api/account Update account info
PUT /api/account/password Update password
DELETE /api/account Delete account
GET /api/api-keys List API keys
POST /api/api-keys Create API key
DELETE /api/api-keys/:id Delete API key

Admin Endpoints

Method Endpoint Description
GET /api/instance/settings Get all instance settings
PUT /api/instance/settings Update instance settings
GET /api/analytics Get secret analytics
GET /api/analytics/visitors/daily Get daily visitor stats
GET /api/invites List invite codes
POST /api/invites Create invite code
DELETE /api/invites/:id Deactivate invite code
PUT /api/user/:id Update user

Example: Create a Secret

curl -X POST https://your-instance.com/api/secrets \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "BASE64_ENCRYPTED_CONTENT",
    "salt": "ENCRYPTION_SALT",
    "expiresAt": 3600,
    "views": 1
  }'

Response:

{
    "id": "abc123xyz"
}

Important Notes

  • Client-side encryption: All secret content should be encrypted client-side before sending to the API. The server only stores encrypted data.
  • Decryption keys: Never send decryption keys to the server. They should be passed via URL fragments (#key=...) which are not transmitted to the server.
  • Rate limiting: API requests may be rate-limited based on instance settings.