Skip to main content

​
Secure integration and documentation hosting

The documentation project contains zero secrets. Your production integration keeps tenant credentials server-side and hands the browser only scoped, expiring capabilities.

Least privilege

Use separate test and live keys with a named scope. Reserve publication and release operations for verified owner/admin sessions.

Opaque identifiers

Keep emails, account IDs, tokens, answers, and report content out of URLs, idempotency headers, logs, analytics, and referrers.

Explicit consent

Use the published consent version and purpose. Optional reusable-profile consent is separate from assessment consent.

Revocable access

Rotate environment and webhook secrets. Use expiring participant and report tokens rather than durable bearer links.

​
Mintlify deployment boundary

  • apps/docs contains public MDX, branding assets, docs.json, and a public OpenAPI deployment copy. It contains no application server or request-time secret access.
  • The canonical OpenAPI file is committed and checked against shared/openapi.json before release.
  • The API playground is disabled. Generated endpoint pages cannot collect a key, execute a mutation, or proxy an authenticated request.
  • Run SYNAPSE_ENVIRONMENT_KEY operations only from your authenticated product backend.
  • If an embedded participant client calls the API directly, allow the exact host origin in Synapse CORS and in the product site’s Content Security Policy.
The generated reference is read-only. It cannot leak a secret through an API console, browser extension, analytics event, copied URL, or persisted request history.

​
Production checklist

  1. Use live only after managed approval; keep test and live data, keys, webhooks, and program IDs separate.
  2. Authenticate the host user before subject sync or session creation. Never accept an arbitrary external ID from the browser.
  3. Persist opaque idempotency IDs and handle 409, 429, timeouts, and ambiguous responses without inventing a new key.
  4. Mask assessment pages in product analytics and disable session replay on assessments and reports.
  5. Exercise deletion and export, legal holds, webhook replay, secret rotation, quota alerts, and restore runbooks before real participant data.
  6. Keep package, SDK, OpenAPI, and server versions aligned through the release bundle.

​
Documentation release checklist

  1. Run npm run sync:openapi --workspace @apart-ai/synapse-docs only when the canonical API contract intentionally changes.
  2. Run npm run check:docs before pushing.
  3. In Mintlify, configure the monorepo content path as /apps/docs.
  4. Verify the GitHub App deployment check is green.
  5. Configure synapse-docs.apart.io in the Mintlify dashboard before adding the Cloudflare CNAME.