Quickstart

1. Get a sandbox

Self-serve a sandbox client scoped to a synthetic deployment. No sales call, no real data.

POST https://api.iwe.alltoogether.com/sandbox/signups
Content-Type: application/json

{ "email": "you@yourcompany.com", "product_name": "Acme Wellbeing" }

You receive a client_id, a client_secret, and a sandbox embed origin. Exchange the credentials for a short-lived access token with client-credentials:

POST /oauth/token
Content-Type: application/json

{ "grant_type": "client_credentials",
  "client_id": "<client_id>", "client_secret": "<client_secret>" }

The response carries a bearer access_token and the granted scopes (respondents:write, checkin:write, aggregates:read, usage:read). The sandbox comes pre-seeded with a synthetic workforce and closed cycles, so aggregates and exports return real, suppressed-where-required data on day one.

2. Embed the check-in

Install the zero-dependency loader:

npm install @alltoogether/iwe-embed

On your server: mint an embed token

Mint a short-lived token (10 minutes, scoped to one respondent) for the signed-in user. Send only a stable user id, never a name. The gateway HMACs it into a pseudonym; names are never stored.

POST /embed/tokens
Authorization: Bearer <access_token>
Content-Type: application/json

{ "respondent_ref": { "partner_user_id": "user-123" } }

Response: { "token": "...", "embed_url": "...", "expires_at": "..." }.

In your frontend: mount it

import IWE from '@alltoogether/iwe-embed';

const handle = IWE.mount('#wellbeing', {
  token,                                       // from your server
  baseUrl: 'https://acme.embed.iwe.alltoogether.com',
  onComplete: () => handle.unmount(),
  onDismiss:  () => handle.unmount(),
});

The iframe renders one question at a time, shows a scoreless "thank you" screen with crisis signposting (Samaritans, Mind, then any employer EAP), and fires onComplete or onDismiss. The loader verifies the postMessage origin, so only the real check-in can fire your callbacks. There is no host-side API that returns an individual's answers or a personal score, by design.

3. Read aggregates

Once a cycle closes, read team aggregates. Every figure arrives with its honesty metadata as one object: you cannot fetch the number without its caveats.

GET /aggregates?cycle=<cycle_id>&unit=<unit_id>
Authorization: Bearer <access_token>

Each row is one of three shapes:

• Shown: value, ci_low, ci_high, n, completion, and a method label of standard (n≥10) or provisional (n 5 to 9, or low completion).
• Withheld: value is null and a suppression_reason is present (below-floor, safeguarding, or low-completion). Render this as a stated refusal, never a blank.

For a portable, vendor-neutral report, export in the open OWHS format:

GET /aggregates/export?cycle=<cycle_id>
Authorization: Bearer <access_token>

The export validates against the public Open Workplace Health Standard schemas, so your compliance team can read it without reading our docs. Suppression, intervals and provisional labels all survive the export. The statistical reasoning behind these fields is on the evidence pages: why n≥5, small-team confidence intervals, and the honesty rules.

4. Certify for production

Before a deployment gets production keys, its rendering is certified: an automated check plus a human review confirm that your dashboard displays the honesty metadata rather than stripping it. Free tiers certify too.

The certification harness checks your rendered dashboard for:

• a confidence interval displayed wherever a value is displayed;
• a provisional badge on every provisional-method row;
• withheld rows rendered as refusals with their coded reason, not as blanks or zeros;
• no sub-threshold value leaking into markup, tooltips or data attributes.

Mark up each aggregate with the certification data attributes (data-iwe-aggregate, data-iwe-value, data-iwe-ci, data-iwe-method, data-iwe-provisional, data-iwe-suppressed, data-iwe-withheld) so the check can read your intent. Run it against your own page, fix what it flags, and submit the passing report. Spot audits repeat the check in production.