Ones

API Documentation

Complete reference for the Ones API. All endpoints require authentication using Bearer tokens.

Authentication

All API requests require a valid Bearer token in the Authorization header.

Authorization: Bearer ones_live_YOUR_TOKEN_HERE

Note: API tokens are configured by the server administrator. Contact your administrator to obtain a token.

Base URL

https://ones.dk/api/v1

Rate Limiting

API requests are rate-limited per token. Rate limit information is included in response headers:

  • X-RateLimit-Limit - Maximum requests per minute
  • X-RateLimit-Remaining - Remaining requests in current window
  • X-RateLimit-Reset - Unix timestamp when the limit resets
  • Retry-After - Seconds to wait if rate limit exceeded (HTTP 429)
GET

/health

Check API health status. Useful for monitoring and uptime checks.

Parameters

None

Response (200 OK)

{
  "status": "ok"
}

Example

curl -X GET "https://ones.dk/api/v1/health" \
  -H "Authorization: Bearer ones_live_YOUR_TOKEN_HERE"
GET

/version

Get the current API version.

Parameters

None

Response (200 OK)

{
  "api_version": "1.0"
}

Example

curl -X GET "https://ones.dk/api/v1/version" \
  -H "Authorization: Bearer ones_live_YOUR_TOKEN_HERE"
POST

/secrets

Create a new one-time secret. The secret must be encrypted client-side before sending.

Request Body (JSON)

{
  "secret": "BASE64_ENCODED_ENCRYPTED_SECRET",
  "iv": "BASE64URL_ENCODED_IV_16_CHARS"
}

Parameters

  • secret (required) - Base64-encoded encrypted secret (max 1MB)
  • iv (required) - Base64URL-encoded initialization vector (exactly 16 characters, no padding)

Response (201 Created)

{
  "uuid": "a3bb189e-8bf9-4c3d-8f4e-35a9b7f8c1d6",
  "url": "https://ones.dk/secret/a3bb189e-8bf9-4c3d-8f4e-35a9b7f8c1d6"
}

Example

curl -X POST "https://ones.dk/api/v1/secrets" \
  -H "Authorization: Bearer ones_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "U2FsdGVkX1...",
    "iv": "abcdefghijklmnop"
  }'

Important: Secrets must be encrypted client-side using AES-256-GCM before sending to the API. The server never sees plaintext secrets.

GET

/secrets/{uuid}

Check if a secret exists without viewing or burning it.

Parameters

  • uuid (path parameter) - UUID of the secret to check

Response (200 OK)

{
  "exists": true,
  "uuid": "a3bb189e-8bf9-4c3d-8f4e-35a9b7f8c1d6"
}

Example

curl -X GET "https://ones.dk/api/v1/secrets/a3bb189e-8bf9-4c3d-8f4e-35a9b7f8c1d6" \
  -H "Authorization: Bearer ones_live_YOUR_TOKEN_HERE"

Note: This endpoint does not retrieve or burn the secret. It only checks existence.

POST

/secrets/{uuid}/burn

Burn (permanently delete) a secret without viewing it.

Parameters

  • uuid (path parameter) - UUID of the secret to burn

Response (200 OK)

{
  "burned": true,
  "uuid": "a3bb189e-8bf9-4c3d-8f4e-35a9b7f8c1d6"
}

Example

curl -X POST "https://ones.dk/api/v1/secrets/a3bb189e-8bf9-4c3d-8f4e-35a9b7f8c1d6/burn" \
  -H "Authorization: Bearer ones_live_YOUR_TOKEN_HERE"

Warning: This action is irreversible. The secret will be permanently deleted.

Error Responses

All error responses follow this format: 

{
  "error": "Error message description"
}

Common HTTP Status Codes

400

Bad Request

Invalid JSON, missing required fields, or validation error

401

Unauthorized

Missing or invalid API token

403

Forbidden

API is disabled on this server

404

Not Found

Secret does not exist or has already been burned

429

Too Many Requests

Rate limit exceeded. Check Retry-After header

500

Internal Server Error

Server-side error. Contact administrator if persists