# Coassemble integration brief

Goal: put a Coassemble course inside your product for a named learner, and find out when they finish.

Facts
- API base: https://api.coassemble.com/api. Use every URL below verbatim, including /api.
- Authorization is the whole key: COASSEMBLE:<workspaceId>:<secret>. Do NOT add a Bearer prefix.
- Keep the key in a server-side .env file. Never put it in browser code, email, or an AI chat.
- If a key is exposed, revoke it in Developer > API keys and create another.
- Published API specification: https://api.coassemble.com/api/docs/json

Steps (the Developer console ticks each one as it happens)
1. GET https://api.coassemble.com/api/v1/headless/courses. Choose a published course from the response. A new workspace normally includes a demo; if none exists, ask the owner to create and publish one.
2. POST https://api.coassemble.com/api/v1/headless/embed/course
   {"action":"view","courseId":"<id from the courses response>","identifier":"<your learner id>"}
   Only add clientIdentifier when you intentionally need to separate customers of your own.
   The link expires in 3 hours. Mint it server-side per learner per page load; do not store it.
3. The response is the signed URL as plain text. Render that URL in an iframe:
   allow="fullscreen; autoplay; presentation; clipboard-write"
   First check whether the app has a server. A static site needs one serverless function that holds
   the key and returns the signed link. The browser must never receive the key.
4. Optional: POST https://api.coassemble.com/api/v1/headless/webhooks {"url":"https://your-server.example/completed","events":["course.completed"],"dataModes":["production","test"]}
   New webhooks default to both live and test data on Sandbox and API Test Mode workspaces;
   workspaces that can choose key modes default to live only. This example explicitly opts into both.
   Webhooks include a boolean testMode. Verify the signature,
   return 2xx, and keep testMode: true events out of production actions. Retries preserve the mode.

Check your work
- After each step, GET https://api.coassemble.com/api/v1/headless/setup/status with the same key.
- Report only the steps that status confirms. Its lastFailure includes a fix; allowances shows learner headroom.
- Reuse one test identifier, such as test-anna. Each new identifier consumes another identified learner.
- Test keys stay test keys after an upgrade. Create a production key when going live.
- Older queued webhooks may omit testMode. Treat a missing flag as unclassified, not production.
- Test SCORM packages expire 30 days after export. Production packages do not expire.
- If you cannot make HTTP calls, say so; the person can watch the steps on the Developer page.

Working example: https://github.com/coassemble/embed-starter

Deliverable: server-side code in the app’s language, plus one link the person can open now.

## Run the starter

Use Node 24, then run these three commands:

```sh
git clone https://github.com/coassemble/embed-starter
cd embed-starter && cp .env.example .env    # paste your key into .env
npm install && COASSEMBLE_API_BASE='https://api.coassemble.com/api' npm run dev    # opens your course
```

The local page opens automatically. If your terminal cannot open a browser, open the URL it prints.