107 lines
4.3 KiB
Markdown
107 lines
4.3 KiB
Markdown
|
# 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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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.
|