API Reference

Sirr exposes HTTP endpoints for secrets management, audit logging, webhooks, and scoped API keys. All endpoints except /health require a Bearer token — either your SIRR_MASTER_KEY or a scoped API key. Requests and responses use JSON.

All authenticated endpoints require the Authorization: Bearer <SIRR_MASTER_KEY> header. The master key is set when you start the server and is used both for authentication and as the seed for encryption.

POST/secrets

Create a secret

Create an encrypted secret. The value is encrypted at rest using ChaCha20Poly1305 with a per-record nonce derived from your master key via Argon2id.

Required attributes

Name
key
Type
string
Description
Unique identifier for the secret. Used to retrieve or delete it later.
Name
value
Type
string
Description
The secret value to encrypt and store.

Optional attributes

Name
ttl_seconds
Type
integer
Description
Time-to-live in seconds. The secret is automatically destroyed after this duration. Omit for no expiration.
Name
max_reads
Type
integer
Description
Maximum number of times the secret can be read. The secret is permanently destroyed after this many reads. Omit for unlimited reads.

Without a valid license key, Sirr allows a maximum of 100 active secrets per instance. Attempting to exceed this limit returns a 402 Payment Required error.

Request

POST

/secrets

curl -X POST http://localhost:39999/secrets \
  -H "Authorization: Bearer $SIRR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "DB_URL",
    "value": "postgres://user:pass@db:5432/myapp",
    "ttl_seconds": 3600,
    "max_reads": 1
  }'

Response (201)

{
  "key": "DB_URL"
}

Error (402)

{
  "error": "secret limit reached",
  "message": "Free tier allows up to 100 active secrets. Set SIRR_LICENSE_KEY to unlock unlimited usage."
}

GET/secrets

List secrets

List metadata for all active secrets. This endpoint never returns secret values — only keys, timestamps, and read counters. This is a deliberate security design choice.

Secret values are never included in list responses. Use GET /secrets/:key to retrieve and decrypt a specific secret.

Request

GET

/secrets

curl http://localhost:39999/secrets \
  -H "Authorization: Bearer $SIRR_MASTER_KEY"

Response

{
  "secrets": [
    {
      "key": "DB_URL",
      "created_at": 1700000000,
      "expires_at": 1700003600,
      "max_reads": 1,
      "read_count": 0
    }
  ]
}

GET/secrets/:key

Retrieve a secret

Retrieve and decrypt a secret by its key. Each call increments the read counter. If the secret has reached its max_reads limit, it is permanently destroyed after this response. Returns 404 if the secret has expired, been burned, or does not exist.

Path parameters

Name
key
Type
string
Description
The key of the secret to retrieve.

Request

GET

/secrets/:key

curl http://localhost:39999/secrets/DB_URL \
  -H "Authorization: Bearer $SIRR_MASTER_KEY"

Response

{
  "key": "DB_URL",
  "value": "postgres://user:pass@db:5432/myapp",
  "created_at": 1700000000,
  "expires_at": 1700003600,
  "max_reads": 1,
  "read_count": 1
}

Error (404)

{
  "error": "not found",
  "message": "Secret does not exist, has expired, or has been burned."
}

DELETE/secrets/:key

Delete a secret

Permanently delete a secret immediately, regardless of its TTL or remaining reads.

Path parameters

Name
key
Type
string
Description
The key of the secret to delete.

Request

DELETE

/secrets/:key

curl -X DELETE http://localhost:39999/secrets/DB_URL \
  -H "Authorization: Bearer $SIRR_MASTER_KEY"

Response

{
  "deleted": true
}

POST/prune

Prune expired secrets

Delete all expired secrets from the database. This is a housekeeping endpoint that reclaims storage by removing secrets whose TTL has elapsed. Returns the count of pruned secrets.

Request

POST

/prune

curl -X POST http://localhost:39999/prune \
  -H "Authorization: Bearer $SIRR_MASTER_KEY"

Response

{
  "pruned": 3
}

PATCH/secrets/:key

Update a secret

Update the TTL or read limit of an existing secret without changing its value.

Path parameters

Name
key
Type
string
Description
The key of the secret to update.

Optional attributes

Name
ttl_seconds
Type
integer
Description
New time-to-live in seconds from now.
Name
max_reads
Type
integer
Description
New maximum read count.

Request

PATCH

/secrets/:key

curl -X PATCH http://localhost:39999/secrets/DB_URL \
  -H "Authorization: Bearer $SIRR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ttl_seconds": 7200 }'

Response

{
  "key": "DB_URL",
  "updated": true
}

Audit logs

Query the append-only audit trail of secret operations. See the full Audit Logs documentation for details.

Endpoint	Description
`GET /audit`	Query audit log entries with filters (since, until, action, key, limit)

Webhooks

Endpoint	Description
`POST /webhooks`	Register a new webhook endpoint
`GET /webhooks`	List all registered webhooks
`DELETE /webhooks/:id`	Remove a webhook

Scoped API keys

Create API keys with granular permissions and optional key prefix restrictions. See the full API Keys documentation.

Endpoint	Description
`POST /keys`	Create a new scoped API key
`GET /keys`	List all API keys (tokens redacted)
`DELETE /keys/:id`	Revoke an API key

GET/health

Health check

Check whether the Sirr server is running and ready to accept requests. This endpoint does not require authentication and is suitable for load balancer health checks and uptime monitoring.

Request

GET

/health

curl http://localhost:39999/health

Response

{
  "status": "ok"
}