Authentication

Patomic uses API keys sent as a Bearer token. Every protected endpoint (everything under /v1/*) requires the header:

Authorization: Bearer ptmc_…

Keys are 256 bits of entropy, base64url-encoded with the prefix ptmc_. They look like:

ptmc_zI7yqBgWoCemHre5bJA3t_g8elCHlB7fK6mNk1tIan0

How storage works

Patomic stores only the hash of your key, never the plain value. The hash is computed with PBKDF2-SHA256 and a server-side HASH_SECRET as deterministic salt — irreversible, with O(1) lookup. Even with full access to the database, an attacker cannot recover any key.

This means the only time you see the plain key is the moment it’s minted. Lose it, mint a new one and revoke the old one — recovery is impossible by design.

Failure modes

A 401 response is identical across every auth failure type — missing header, malformed header, unknown key, revoked key, expired key, soft-deleted user. The audit log keeps the precise reason for forensics; the response never leaks it. This means an attacker probing keys cannot distinguish “this key was once valid” from “this key never existed”. See Errors → unauthorized.

Key lifecycle

Action	Endpoint	Method	Notes
Mint	/v1/keys	POST	Returns plain_key exactly once
List	/v1/keys	GET	All keys for the authenticated user, paginated
Inspect	/v1/keys/{id}	GET	Public metadata, no plain
Update	/v1/keys/{id}	PATCH	Rename, change rate limit, change expiry
Revoke	/v1/keys/{id}	DELETE	Idempotent. Soft-revoke (revoked_at set; row preserved).

A revoked key is never reactivated — that’s intentional. Mint a new one; the old one stays in the audit trail forever.

Rate limits

Each key has a rate_limit_rpm (requests per minute). The default is 60; admins can mint keys with up to 100,000 rpm. Atomic enforcement means no burst leaks past the limit. See Rate limits for the algorithm.

Best practice

• Treat ptmc_ keys as you’d treat OAuth tokens. Never commit them, never send them to a frontend, never log them.
• Use separate keys per environment: dev, CI, staging, production. Mint with descriptive names.
• Rotate proactively when an engineer leaves, when a CI runner is replaced, or annually as a discipline.
• The key_prefix (first 12 chars) is the safe value to log or display in dashboards.