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/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,
    "screens": [],
    "theme": null,
    "folder": null,
    "identified": false,
    "private": false,
    "paid": false,
    "price": 1,
    "key": "abc123",
    "identifier": "user_123",
    "clientIdentifier": "client_123",
    "revision": "example",
    "published": "2026-05-28T03:44:41.275Z",
    "translations": [
      "example"
    ],
    "created": "2026-05-28T03:44:41.275Z",
    "updated": "2026-05-28T03:44:41.275Z",
    "deleted": "2026-05-28T03:44:41.276Z"
  }
]

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		—

Examples

cURL request

curl --request POST \
  --url "https://api.coassemble.com/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.

<iframe src="SIGNED_EMBED_URL"></iframe>

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.