Authentication and scope

Choose the narrowest credential for the actor and keep every secret on its intended side of the server/browser boundary.

Credential	Header or transport	Allowed use	Never
Environment key (`syn_test_…` or `syn_live_…`)	`Authorization: Bearer …` or `X-API-Key`	Trusted server integration in one app and environment	Browser bundle, static content, mobile client, URL, analytics
Human session	Secure HttpOnly session cookie	Owner/admin publication, activation, review release, and share management	SDK configuration or cross-origin forwarding
Participant token (`spt_…`)	`Authorization: Bearer …`	One short-lived participant session	Queue key, URL query, logs, local storage, or another evaluation
Report-share token (`shr_…`)	`Authorization: Bearer …`	One expiring and revocable public report	UUID-only report access or query parameters
Webhook secret	`X-Synapse-Signature` verification	Verify the exact raw delivery body	Parsing first, browser exposure, or signature logging

Environment key scopes

admin/ops: server-side subject, program, session, result, analytics, and integration operations.
ingest: subject upsert/import plus continuous-evaluation event, due-question, and answer writes.
Continuous current alignment and drift reads require admin or ops.
Environment keys cannot publish definitions or bundles, activate programs, release reviewed results, or create and revoke public report shares.

Mintlify documentation is public content, not a trusted application backend. Never add an environment key to an MDX file, docs.json, OpenAPI example, or API playground. Run SDK calls in your separately authenticated server and return only a short-lived participant handoff.

Credential rotation

Create overlapping environment or webhook secrets, update consumers, verify traffic, then revoke the old secret. A key’s one-time plaintext is returned only at creation or rotation, and durable replay receipts expire after 24 hours.