Skip to main content
Use this checklist after the quickstart works locally. It separates package correctness, application behavior, Gateway authorization, and production observation so one green lane is not mistaken for all four.

​
Reference architecture

​
Before deployment

​
Package and contract

  • Pin @praxa/sdk to an reviewed version.
  • Run a clean install and import @praxa/sdk, @praxa/sdk/tools, and any used subpath.
  • Assert PRAXA_OPENAPI_VERSION and PRAXA_OPENAPI_SHA256 in CI.
  • Review changed route contracts before upgrading.
  • Keep Aura-compatible wire names unchanged.

​
Authentication and tenancy

  • Keep OAuth tokens in the trusted backend.
  • Derive tenant, subject, and purpose from the authenticated principal.
  • Request only scopes used by that route.
  • Set token expiry and revocation behavior.
  • Deny organization or shared scopes unless your deployment explicitly supports and tests them.
  • Prove a foreign identifier cannot disclose another tenant’s resource.

​
Mutations and retries

  • Generate one stable idempotency key per logical mutation.
  • Store the key and normalized request body together before sending.
  • Reuse both after a timeout or ambiguous network failure.
  • Never reuse a key for changed input.
  • Reconcile uncertain outcomes through authoritative readback.
  • Bound total attempts and elapsed time.

​
Events and lifecycle

  • Persist the latest processed event ID per run.
  • Resume SSE with lastEventId after reconnect.
  • Tolerate duplicate delivery by event ID.
  • Separate stream closure from terminal mission success.
  • Read the mission projection after reconnect or terminal events.
  • Cancel the local stream when the application request ends.

​
Observability

Record: Never record bearer tokens, authorization headers, provider secrets, raw memory content, arbitrary goal payloads, or unredacted traces.

​
Required automated tests

Use injected fetch for unit and contract tests. Use disposable principals and least-privilege tokens for staging authorization tests.

​
Deployment sequence

1

Deploy the backend with calls disabled

Verify package imports, configuration, and health without accepting user work.
2

Run negative canaries

Test missing, expired, under-scoped, revoked, and cross-tenant requests. Negative tests should fail before the positive lane is opened.
3

Run one disposable positive mission

Admit it, consume events, read the terminal projection, and preserve the correlation receipt.
4

Increase traffic gradually

Watch authorization failures, retry exhaustion, SSE reconnects, terminal status distribution, latency, and resource use.
5

Exercise rollback

Restore the previous package and configuration without invalidating persisted idempotency keys or event cursors.

​
Operational alerts

Alert separately on:
  • sustained 401 increases, which often indicate token issuance or audience problems;
  • 403 increases, which indicate scope, tenant, or policy denial;
  • 409 increases, which can reveal idempotency-body drift;
  • 429 responses and retry exhaustion;
  • SSE reconnect storms or stale cursors;
  • missions remaining non-terminal beyond your product deadline;
  • terminal failures grouped by problem code;
  • unexpected contract fingerprint at startup.

​
Upgrade procedure

  1. Install the new version in an isolated branch.
  2. Compare exported declarations and route contracts.
  3. Update the pinned contract fingerprint deliberately.
  4. Run unit, negative authorization, idempotency, SSE, and staging canaries.
  5. Deploy gradually and retain the previous artifact for rollback.
  6. Do not delete historical cursors or idempotency records during the package upgrade.

​
Completion evidence

An integration is production-qualified only when you can point to:
  • a reviewed source revision and locked package version;
  • passing application and SDK contract tests;
  • authenticated least-privilege positive and negative canaries;
  • a terminal mission readback for disposable work;
  • redacted production observability;
  • a tested rollback path;
  • user acceptance for the actual product workflow.

Test your integration

Run the shared success, isolation, idempotency, outage, stream, and cleanup matrix before production traffic.
Last modified on August 14, 2026