Skip to content

docs: cryptify api-key tier validates against pkg, not local allowlist - #51

Merged
rubenhensen merged 1 commit into
mainfrom
docs/api-key-validation
May 6, 2026
Merged

docs: cryptify api-key tier validates against pkg, not local allowlist#51
rubenhensen merged 1 commit into
mainfrom
docs/api-key-validation

Conversation

@rubenhensen

Copy link
Copy Markdown
Contributor

Summary

Reflects the change in:

The user-facing docs change is small but specific: the higher upload-quota tier on Cryptify is now unlocked by a validated `Authorization: Bearer PG-…`, not by mere presence of an `X-Api-Key` header. This PR pins the new behaviour, the failure modes (especially 503 when PKG is unreachable for over-default uploads), and updates the API-endpoint tables.

Pages touched

  • `docs/repos/cryptify.md`
    • Upload-limits table column rename: "Anonymous senders" → "Default tier", "API-key senders" → "API-key tier". The previous wording suggested presence-of-header was the gate.
    • Note that the API-key tier accounts on the tenant id (`api-key:<organizations.id>`), not the sender email — so a single tenant cannot evade quota by varying sender attributes.
    • New "Authentication for the higher tier" section: bearer flow, per-init validation, 30 s retry budget, the four validation outcomes table, and the 503-vs-413 distinction when PKG is unreachable.
    • `GET /usage` note: response describes the per-tenant bucket when called with the bearer.
    • Note that the legacy `X-Api-Key` header is no longer recognised.
  • `docs/guide/architecture.md`
    • Add `/v2/api-key/validate` to the PKG endpoints table.
    • Cryptify endpoints: note that `init`/`PUT` carry an optional `Authorization: Bearer PG-…`, with a link to the Cryptify page for the full breakdown.
  • `docs/guide/concepts.md`
    • "API key signing (PostGuard for Business)": a sentence on the higher upload-quota tier the same key unlocks via Cryptify, with a link.
  • `docs/repos/postguard-js.md`
    • Inline comment on `pg.sign.apiKey()`: the SDK forwards the key to Cryptify uploads automatically.

Build

`npx vitepress build docs` → clean. No broken links.

Deploy ordering

This doc PR can merge whenever, but the described behaviour ships in the order: postguard#167 → cryptify#139 → postguard-js#43. Until those PRs land in production, the page describes the future state. If that's a concern, hold this PR on the gh draft until cryptify#139 is at least in staging.

Test plan

  • `npm run build` (or local `npm run dev`) renders the four touched pages without warnings
  • Spot-check the new section on `docs/repos/cryptify.md#authentication-for-the-higher-tier`: anchor link from `docs/guide/architecture.md` resolves
  • Spot-check the new `#upload-limits` link from `postguard-js.md` and `concepts.md`

Reflects the change in encryption4all/postguard#167 (new
/v2/api-key/validate endpoint), encryption4all/cryptify#139 (cryptify
calls it), and encryption4all/postguard-js#43 (SDK forwards the bearer).

repos/cryptify.md
- Upload-limits table: rename "Anonymous senders" to "Default tier" /
  "API-key tier" so the column meaning matches the auth header you send.
- Note that API-key tier accounts on the tenant id, not sender email.
- New "Authentication for the higher tier" section: bearer flow, per-init
  validation, retry budget, the four validation outcomes, and the 503-
  vs-413 distinction when pkg is unreachable.
- Note that GET /usage returns the per-tenant bucket when called with
  Authorization: Bearer PG-...
- Note that the legacy X-Api-Key header is no longer recognised.

guide/architecture.md
- Add /v2/api-key/validate to the PKG endpoints table.
- Cryptify endpoints: note that init/PUT carry an optional
  Authorization: Bearer PG-..., and link to the cryptify page for the
  full breakdown.

guide/concepts.md
- "API key signing" section: a sentence on the higher upload-quota tier
  the same key unlocks via Cryptify, with a link.

repos/postguard-js.md
- Inline comment on pg.sign.apiKey(): the SDK forwards the key to
  Cryptify uploads automatically; link to the Cryptify upload-limits.
@rubenhensen
rubenhensen marked this pull request as ready for review May 6, 2026 12:25
@rubenhensen
rubenhensen merged commit afea70d into main May 6, 2026
1 check passed
@rubenhensen
rubenhensen deleted the docs/api-key-validation branch May 6, 2026 12:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant