Authentication

Every request to the Sirr API must include a bearer token. Sirr uses a single master key for authentication — there are no API key pairs, OAuth flows, or session cookies. Set SIRR_MASTER_KEY when you start the server and pass it as a bearer token with every request.

Bearer token

Sirr authenticates requests using the SIRR_MASTER_KEY environment variable. This key serves a dual purpose: it is both the bearer token for API authentication and the seed for Argon2id key derivation used to encrypt secrets at rest.

When the server starts, it reads SIRR_MASTER_KEY from the environment. Every incoming request's Authorization header is compared against this value using a constant-time comparison to prevent timing attacks.

export SIRR_MASTER_KEY="your-secret-master-key"
sirr

Making authenticated requests

Include the token in the Authorization header as a standard Bearer token. Every endpoint except the health check requires authentication.

Authorization: Bearer <token>

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

SDK examples

If you use one of the official SDKs, pass the token once when constructing the client and every request is authenticated automatically.

import { SirrClient } from '@sirr/node'

const sirr = new SirrClient({
  server: process.env.SIRR_SERVER,
  token: process.env.SIRR_TOKEN,
})

const secret = await sirr.get('db/password')

Scoped API keys

For production environments where sharing the master key is undesirable, Sirr supports scoped API keys. Each key has explicit permissions (read, write, delete, admin) and an optional key prefix restriction.

Scoped keys authenticate the same way — via the Authorization: Bearer <key> header. The server determines what the key is allowed to do based on its permissions.

# This key can only read secrets under the "ci/" prefix
curl http://localhost:39999/secrets/ci/deploy-token \
  -H "Authorization: Bearer sirr_sk_7f3a..."

Common patterns

Token security

The master key is the single credential that protects your entire Sirr instance. Follow these guidelines to keep it safe.

• Use TLS in production. Without HTTPS the bearer token is sent in plaintext over the network. Always terminate TLS in front of Sirr — via a reverse proxy, load balancer, or service mesh.
• Never commit tokens to git. Use environment variables, a .env file excluded from version control, or a secrets manager like Vault or AWS Secrets Manager.
• Rotate carefully. Changing SIRR_MASTER_KEY invalidates all existing encrypted secrets because the Argon2id-derived encryption key changes. Plan a migration window if you need to rotate.
• Constant-time comparison. Sirr compares the provided token against the master key using a constant-time algorithm, preventing timing side-channel attacks that could leak the key one character at a time.
• Limit network exposure. Bind Sirr to 127.0.0.1 or a private network interface when it does not need to be publicly reachable.