Get Started

Let's get you ready to ship a basic Coassemble integration: authenticate, request a signed embed URL, and render it in an iframe. We recommend starting with a learner-facing course embed, then expanding to other embeddables as needed.

Before you begin

Your workspace has the API enabled and you have a workspace API key. You can generate or regenerate the key from your workspace API settings.
You have at least one course in Coassemble that you can embed.
You have a stable identifier from your app (for example, a user ID from your database). This is used to identify your learner within Coassemble.

Entitlements

The API and embeddables are gated behind a paid plan with API access enabled. Authoring, analytics, advanced, and SCORM features each require their own entitlement on top of base API access — endpoints that need these will return a 403 FORBIDDEN if your plan does not include them. See the plan matrix on the Coassemble pricing page.

1. Set your Authorization header

Every request to the Coassemble API uses this format. The key encodes your workspace ID, so it is the entire header value.

Authorization: COASSEMBLE:<YOUR_WORKSPACE_ID>:<YOUR_API_KEY>

2. Fetch a course ID to embed

If you do not already have a course ID, fetch your courses and select one.

GET/v1/headless/courses

Query parameters

Field	Type	Required	Default	Options
`identifier`	`string`	No	—	—
`clientIdentifier`	`string`	No	—	—
`length`	`number`	No	`100`	—
`page`	`number`	No	`0`	—
`title`	`string`	No	—	—
`deleted`	`boolean`	No	`false`	—

Examples

cURL request

curl --request GET \
  --url "https://api.coassemble.com/api/v1/headless/courses?identifier=user_123&clientIdentifier=client_123&length=100&page=0&title=Workplace+Safety&deleted=false" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY"

Response

JSON response

[
  {
    "id": 1234,
    "active": false,
    "title": "Workplace Safety",
    "description": "example",
    "image": "example",
    "thumbnail": "example",
    "thumbnailRevision": "example",
    "thumbnailOutdated": false,
    "start": null,
    "finish": null,
    "theme": null,
    "folder": null,
    "identified": false,
    "private": false,
    "paid": false,
    "price": 1,
    "key": "abc123",
    "identifier": "user_123",
    "clientIdentifier": "client_123",
    "revision": "example",
    "published": "2026-06-17T20:43:42.955Z",
    "translations": [
      "example"
    ],
    "created": "2026-06-17T20:43:42.955Z",
    "updated": "2026-06-17T20:43:42.955Z",
    "deleted": "2026-06-17T20:43:42.955Z"
  }
]

3. Request a signed embed URL

Request a signed URL for the course player. For a learner integration, the minimum body you will need is action, courseId, and identifier.

POST/v1/headless/embed/course

Body parameters

Field	Type	Required	Desc	Options
`action`	`string`	Yes	view (learner) or edit (authoring)	`viewedit`
`courseId`	`number`	No	Course ID (required when action is view)	—
`identifier`	`string`	Yes	Your stable user identifier	—
`clientIdentifier`	`string`	No	The client this user belongs to	—
`themeId`	`number`	No	Theme ID to render the embed with	—
`name`	`string`	No	Display name for the learner	—
`avatar`	`string`	No	Avatar URL for the learner	—
`options`	`object`	No		—
`readonly`	`boolean`	No	When true, mutating requests from this embed are silently no-opped server-side.	—

Examples

cURL request

curl --request POST \
  --url "https://api.coassemble.com/api/v1/headless/embed/course" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "action": "view",
    "identifier": "user_123",
    "courseId": 1234,
    "clientIdentifier": "client_123"
}'

Response

JSON response

"https://api.coassemble.com/embed/abc123def456"

4. Render the signed URL in an iframe

Put the signed URL returned by the embed endpoint into your iframe src.

info

Iframe permissions: Browsers gate what an embedded page can do. Use the iframe allow attribute (Permissions Policy) to delegate capabilities to Coassemble. If you also set sandbox, most features stay blocked until you opt in with sandbox flags and, for some APIs, matching allow tokens.

The embed code in the Coassemble app (Share → Embed) and the live demos in these docs start from the permissions below. Add or remove entries to match your security model and the features your learners use.

<iframe
  src="SIGNED_EMBED_URL"
  allow="fullscreen; autoplay; presentation; clipboard-write"
></iframe>

`allow` token	Typical use in Coassemble
`fullscreen`	Fullscreen video, SCORM, and player chrome.
`autoplay`	Course and collection media (subject to browser autoplay rules).
`presentation`	Presentation API access on video pages (e.g. Chrome Cast discovery).
`clipboard-write`	Optional; included in API docs demos where the host copies integration snippets.
`camera`, `microphone`	Only if course content uses learner recording or similar capture screens.
`picture-in-picture`, `encrypted-media`	Only if you rely on third-party players inside courses that need them.

With sandbox, you must usually include at least allow-scripts allow-same-origin so the player can run. For presentation-related APIs, add allow-presentation on sandbox and keep presentation in allow when needed. Other sandbox flags (for example allow-popups, allow-forms, allow-downloads) depend on how learners interact with your host page.

Missing permissions often surface as console SecurityError or NotAllowedError messages rather than Coassemble API failures. If something works on a plain iframe but breaks after you tighten sandbox or allow, grant the matching capability and retest.

info

Security requirements: The workspace API key must be stored exclusively on your server — the browser never holds it. Generate a fresh signed URL per user per page load; do not cache or reuse signed URLs across different users or sessions. Direct browser-to-API calls are not supported.

Next steps

Handle learner events via window.postMessage (progress, completion, quiz events) from the Course Player embeddable.
Embed authoring with action: edit if you want to allow your users to create courses in your platform.
Use other embeddables (collections, analytics, lists, cards) from the Embeddables section.