unauthorized

HTTP/1.1 401 Unauthorized
{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "Missing or invalid API key.",
    "docs_url": "https://docs.patomic.dev/errors/unauthorized",
    "request_id": "…",
    "suggestion": "Send your API key as `Authorization: Bearer ptmc_…`. Verify the key is active in your dashboard."
  }
}

What it means

The request did not include a valid, active API key.

What causes it

By design, Patomic returns the same response for every authentication failure. The audit log records the precise sub-reason; the public response does not. Sub-reasons that all surface as unauthorized:

• Missing header. No Authorization was sent.
• Wrong scheme. Sent Basic, Token, or anything other than Bearer.
• Wrong prefix. The token does not start with ptmc_.
• Unknown key. The key was never minted, or was minted under a different HASH_SECRET (e.g. local dev key against production).
• Revoked. The key was revoked via DELETE /v1/keys/{id}.
• Expired. The key’s expires_at has passed.
• User soft-deleted. The user owning the key has deleted_at set.

How to fix

1. Check the header format — Authorization: Bearer ptmc_…, no extra whitespace, no quotes.
2. Confirm the key is active — GET /v1/keys/{id} with another working key. If revoked_at is non-null, mint a new key.
3. Confirm you’re hitting the right environment — keys minted against local dev (--local) won’t work against the production URL, and vice versa. They’re hashed under different HASH_SECRET values.
4. If you’re certain the key should work, include the request_id from the 401 response when contacting support — Patomic can look up the precise sub-reason in the audit log.

Why we don’t tell you which sub-reason

If the response said “this key was revoked” vs “this key never existed”, an attacker probing for valid keys could distinguish “key X was once valid” from “key X never existed” — useful intelligence for them, useless for you. The audit log is the right place for this; the wire response isn’t.

Related

• Authentication concept
• Errors envelope