Coordinated releases

MicroAuth has one protocol implemented by several repositories. Release the API, FastAPI SDK, portal, SaaS app and docs as a compatibility set.

Contract-changing release order

1. Add backward-compatible database state and API request handling.
2. Deploy the API and worker.
3. Verify old SDK and SPA versions still work.
4. Release the SDK and SPAs that use the new contract.
5. Remove legacy API compatibility only in a later release.
6. Generate OpenAPI from the final local API commit and update docs.

For the production-readiness protocol, verify these exact contracts together:

• snapshots and key verification return a per-customer usage_policy_id and policy_valid_until;
• usage items use idempotency_key, api_key_id, usage_policy_id, status_code, count and RFC 3339 period_start, and every authenticated response is reported;
• usage responses acknowledge each item as accepted, duplicate, rejected, or retry;
• snapshots include authoritative platform monthly limit, used, remaining, period end and hard-cap fields, plus the released SDK compatibility object;
• monthly request allowances are pre-handler controls in conforming SDKs, not a trusted gateway guarantee against an API owner that bypasses the SDK;
• authenticated portal team requests send X-MicroAuth-Workspace-ID;
• plan IDs are UUID strings or null, while plan names are strings or null;
• Stripe payment failure exposes the same 7-day grace and billing_suspended lifecycle to the API and UIs.

OpenAPI snapshot

The docs tooling accepts only a local file or stdin. It never downloads the production API.

Generate the contract directly from the final API commit. This command registers the Huma operations without starting PostgreSQL, Redis, or an HTTP server:

cd api
go run ./cmd/openapi > /tmp/microauth-openapi.json

cd ../docs
node scripts/openapi.mjs check /tmp/microauth-openapi.json

Drift is expected after an intentional API change. Review the generated file, sync it, then rerun the check and full docs build:

node scripts/openapi.mjs sync /tmp/microauth-openapi.json
node scripts/openapi.mjs check /tmp/microauth-openapi.json
npm run check

Never refresh public/openapi.json from https://api.microauth.com. That can publish a partially deployed or older production contract and makes the source commit impossible to reproduce.

SDK release

• bump package metadata and changelog together;
• run tests, lint, type checks, build, package inspection and a clean wheel install on every supported Python version;
• test both the memory and Redis backends, with multiple keys and workers;
• verify timeout retries keep stable item IDs and partial acknowledgements keep every unacknowledged item;
• verify graceful shutdown either drains or reports durable pending work;
• publish only after the compatible API is live and its migration is healthy.

Web and docs release

Run npm ci and npm run check in both docs and website. Review generated asset URLs, canonical host, social metadata, dynamic pricing success and failure states, private-plan isolation and portal team tab isolation.

The static sites contain no fallback price list. If the pricing API is unavailable, the website shows a loading or error state and lets the visitor retry.

Release record

Record component versions, commits, migrations, OpenAPI digest, SDK package digest, deployment artifacts, credential rotations, smoke tests and known compatibility windows. Link an incident or rollback note when any gate was waived.