Authentication & Rate Limits

Authentication Models

The Torch uses two distinct auth mechanisms depending on the caller type.

API Key Auth — Read Engines

All five read engines (/v1/veritas, /v1/devotio, /v1/ordo, /v1/corpus) require an API key issued through the Developer Portal.

Pass the key in the X-API-Key header on every request:

curl https://api.torchandlily.com/v1/devotio/saints \
  -H "X-API-Key: tl_your_key_here"

Keys are stored as SHA-256 hashes — the plaintext is shown only once at creation. If lost, revoke and generate a new key.

Error responses:

Status	Meaning
`401 Unauthorized`	Missing, invalid, or revoked API key

Tenant Auth — Communio Engine

The Communio prayer network (/v1/communio) is a write engine for registered applications. It uses the same X-API-Key header but validates against a separate tenant registry (communio.applications).

To request Communio access, contact the Torch & Lily team. Tenant keys grant permission to submit prayer intentions and receive webhook callbacks on intercession events.

JWT Auth — Developer Portal

The portal API (/portal/keys, /portal/me) is for authenticated dashboard users. It requires a Supabase-issued JWT passed as a Bearer token:

curl https://api.torchandlily.com/portal/me \
  -H "Authorization: Bearer eyJhbGciOi..."

JWTs are obtained automatically when you sign in via Google or GitHub OAuth through the Developer Portal.

Obtaining an API Key

Sign in to the Developer Portal via Google or GitHub.
In your dashboard, click New Key, enter a descriptive name, and confirm.
Copy the key immediately — it will not be shown again.
Revoke any key from the same dashboard if it is compromised.

Rate Limits

The read engines enforce a sliding-window rate limit per API key.

Engine	Limit
Veritas, Devotio, Tempus, Corpus	200 requests per 15 minutes
Communio (writes)	50 submissions per hour (per tenant key)

Every response from a rate-limited engine includes quota headers:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 142
X-RateLimit-Reset: 1743026700

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix epoch second when the window resets

When a limit is exceeded, the API returns 429 Too Many Requests with the same headers plus Retry-After (seconds until a slot opens). Well-behaved clients should throttle proactively using X-RateLimit-Remaining rather than waiting for a 429.

N.B. Rate limit state is held in-process and resets on server restart. This is acceptable for the current single-instance deployment. Redis-backed limits will be introduced if horizontal scaling is required.

Security Notes

Never embed an API key in client-side code or public repositories.
Rotate keys periodically, especially after personnel changes.
The Communio engine’s tenant keys carry write permissions — treat them with heightened care.