When you embed a Coassemble experience in your own product, you can pass through a unique identifier so that the recipient counts as an Identified Recipient (IR) and their progress is attributed to a specific person. If you’re using an Embed plan with multi-tenancy, you can also scope sessions to the correct tenant so usage and reporting stay isolated. This article explains the concepts; for the actual request shape and current field names, see the developer documentation.

When you embed a Coassemble experience in your own product, you can pass through a unique identifier so that the recipient counts as an Identified Recipient (IR) and their progress is attributed to a specific person. If you’re using an Embed plan with multi-tenancy, you can also scope sessions to the correct tenant so usage and reporting stay isolated. This article explains the concepts; for the actual request shape and current field names, see the developer documentation.

## Multi-tenancy overview (Embed Core and above)

Embed plans support multi-tenancy by letting you represent multiple customer tenants within a single workspace, while keeping identity, access, and reporting scoped per tenant.

A common model is:

* **One workspace**
* **Multiple isolated tenants** inside that workspace

You typically create and manage tenants programmatically via the **Coassemble API**. Use the developer documentation as the source of truth for endpoint paths, request bodies, and parameter names:

* https://developers.coassemble.com

### What Embed Core supports

Embed Core can be used to implement multi-tenancy by scoping identity, access, and reporting to a tenant context.

Key points:
- Multi-tenancy is implemented within a single workspace.
- Tenants are created and managed programmatically via the API.
- Embedded sessions are scoped by passing identity and tenant context when requesting a signed embed URL.

## How tenant scoping works for embedded sessions

When your backend requests a signed URL from the Coassemble API for an embedded surface (a Course Player, Collection Player, or any other embeddable), you include:

1. **An identifier** (so progress is attributed to a person)
2. **Tenant scoping fields** (so the session is associated with the correct tenant)

This ensures usage and activity are attributed to the correct tenant.

From there, Coassemble:

* Counts the recipient as one Identified Recipient (IR) per unique identifier per period.
* Attributes the session's events (start, progress, completion) to that identifier.
* Associates usage and activity with the correct tenant so reporting and tracking remain isolated.

Reference:
- https://app.brainfi.sh/doc/passing-identity-and-tenant-context-in-embedded-sessions-stJkH9Zy5x

### Important: field names can change

Some internal materials may reference specific field names (for example, `tenant_id` and `customer_id`). Treat these as illustrative only—use the **developer documentation** as canonical for the current parameter names and request shapes:

* https://developers.coassemble.com

## Signed embed URL expiration (TTL) and session expiration in iframes

When embedding a Coassemble experience (for example, in an `<iframe>`) using a signed URL, it helps to separate two concepts:

- **Signed URL expiry**: whether the URL is still valid for *initializing* an embed.
- **Embedded session expiry**: whether the already-initialized learner session is still active.

### Signed URL expiry: what to expect

- The signed URL is **consumed at iframe load time** to initialize the embedded experience.
- Once the iframe has loaded and a session is established, the learner’s in-progress experience is **not continuously re-validated against the signed URL**.
- Practical implication: a learner who is already in the player generally **will not be interrupted** merely because the original signed URL reaches its TTL.

If an expired (or otherwise invalid) signed URL is used to load the iframe (for example, if the host app reloads the iframe using a cached URL), the embed will **fail to initialize** rather than silently re-authenticate.

### Embedded session expiry (inactivity): what to expect

- Embedded sessions have a **3-hour TTL**.
- The session can be **refreshed by activity**.
- If the session truly expires (for example, it crosses the 3-hour mark with **no activity to trigger a refresh**), the embeddable emits a **`session.expired`** event.

## Refresh behaviour (recommended patterns)

Signed embed URLs used for embedded sessions expire after a fixed time-to-live (TTL). Integrations should generate fresh signed URLs and implement a refresh/recovery flow.

### Expiration TTL

- **TTL:** `3 hours`

### Refresh behaviour

- **Refresh window:** when the user takes an action and the current signed token is **within 1 hour of expiry**, generate a new signed token and return it to the frontend.
- This supports **automatic session refresh** as expiry approaches (without forcing the user to restart).

> Note: historically, the exact TTL was not documented publicly. Avoid committing to different expiry values externally until the Developer Docs are updated.

### Usage requirements (do not cache)

Follow this pattern when working with signed embed URLs:

- Generate a **fresh signed URL per user per page load**.
- **Do not cache or reuse** signed URLs across different users or sessions.

## Handling `session.expired` (recommended integration pattern)

To make embedded experiences resilient:

1. **Generate a fresh signed URL per user per page load.** Do not cache or reuse signed URLs across users or sessions.
2. **Listen for embeddable events** via `window.postMessage`.
3. **Handle `session.expired`** by prompting a recovery flow, such as:
   - Request a new signed URL from your backend, then
   - Update the iframe `src` (or reload the iframe) to re-initialize the experience.

Additional notes:
- **No silent re-auth is documented** as the expected behavior when an iframe attempts to load with an expired signed URL; plan for a detectable failure on initialization.
- Use the event stream as the primary mechanism to detect runtime session lifecycle changes, including expiration.

## What Embed Automate adds (vs Embed Core)

Multi-tenancy is available from **Embed Core** and above. **Embed Automate** primarily adds tooling to customize and manage embeddable branding and tenant operations at scale:

* **Themes API (CRUD):** create and manage **themes for the embeddable UI** programmatically (for example, via `GET`, `POST`, `PUT`, `DELETE` on theme endpoints).
* **Selecting a theme for an embed (where supported):** some implementations support choosing which *embeddable UI theme* is used for a given embedded surface (for example, via a `themeId`). This is for **whitelabeling the embedded experience** and should not be positioned as “theming the learning content” at delivery time.

On Embed Core, embeddable branding may require more manual in-app theme assignment, which can be harder to scale across many tenants.

## Themes API: correct framing

### What the Themes API is for

The **Themes API** allows integrators to create and manage themes for the **embeddable itself** (whitelabeling the embedded UI).

Use it to:
- Apply integrator branding to the embeddable experience
- Manage the embeddable look-and-feel programmatically (CRUD)

### What the Themes API is not for

Do **not** describe the Themes API as:
- A way to create **per-tenant themes for course/content**
- A way to apply themes/branding to learning content at delivery time

Correct positioning: **Themes API enables whitelabeling of the embeddable UI, not theming of the content.**

## What an identifier is in an embed context

An identifier is any stable value that uniquely represents the person taking the course. It might be:

* An email address.
* An internal user ID from your own platform (for example, a UUID).
* Any stable value you already use to identify the person in your system.

Whatever you pass becomes the IR record for that session.

## What happens if you don't pass an identifier

The session counts as an Anonymous Recipient (AR), tracked at the device and session level. This is fine for broadly available content but means you won't be able to link the recipient's progress back to a specific person in your system.

## Best practices

* **Use a stable identifier per person.** The same email or user ID should produce the same IR across multiple sessions, so usage and progress accumulate against one record.
* **Pick one convention per person and stick to it.** If you use email for some sessions and an internal ID for others (for the same person), you'll create two IRs.
* **Don't recycle identifiers across different people.** Doing so will merge their progress.

## Managing tenant AI usage (if applicable)

### AI usage caps per tenant (all Embed plans)

AI generation limits are enforced at the **tenant** level.

Defaults (per tenant):
- 250,000 narration tokens/month
- 150 AI image generation events/month

Notes:
- These are hard caps per tenant; once a tenant reaches its cap, AI generation is blocked for that tenant until the cap is raised or the month resets.
- Other tenants (and the parent customer) are not impacted by one tenant hitting its cap.
- A tenant can be set to "unlimited" so it draws from the customer-level pool.

Reference:
- https://app.brainfi.sh/doc/managing-tenant-caps-7jY5bS2rJA

### Non-AI usage

- `IR/AR` counts are enforced at the **customer** level (not capped per tenant).

## Where to find the request shape

For the actual API endpoints, request fields, and identifier/tenant scoping formats, see the developer documentation:

* https://developers.coassemble.com

## Additional positioning guidance

If a prospect’s primary requirement is **whitelabeling the embeddable UI**, highlight the Themes API.

If a prospect requires **per-tenant branding of content at scale**, do not position the Themes API as the solution; clarify current options and the operational effort involved (for example, manual assignment inside the app) and align on the best plan/approach based on their needs.

## Common questions

### Where do I see how many IRs I'm using?

Open **Settings** and select **Usage limits**. You can also query usage programmatically via the Per-Tenant Usage Reporting API (Embed plans).

### Can I pass identity in a Flow embed?

Flow is anonymous-only. Embedded sessions on Flow do not preserve identifiers, and all Flow recipients count as ARs.

### What if my system uses email for some users and an internal ID for others?

Both work. Pick one convention per person. Switching identifier type for the same person creates two IRs.


Passing identity (and tenant context) in embedded sessions

API keys

Notion

YouTube

Hubspot

Arcade

Vimeo

Unsplash

360Learning

aNewSpring

Docebo

Embed and Stripe: How to Sell Access Using Your Own Checkout and Coassemble Embed

Connections & Integrations

Release notes

General

What is Coassemble?

Coassemble terminology explained

Accessing the login page

Getting to know your Coassemble workspace

Build the business case for Coassemble

Getting started: Common questions

How do I sign up for a Coassemble account?

What file types can I transform into a course?

What is a screen?

What tone should I select?

What is a collection?

Can I use Coassemble as an LMS?

How to log in to your account

Getting started

Connecting to Google Drive or OneDrive

Convert a presentation into an online course

Your knowledge

Usage limits

Identified Recipients and Anonymous Recipients

Logging in with Microsoft

Folders

Creators

Transfer ownership of your workspace

Configuring your email preferences

Common questions: Workspaces

How to delete a creator

Managing account, workspace, and billing settings

Organizing courses with folders

Your workspace & settings

How to upload custom fonts in Coassemble

How to save a legacy course theme

Brand kit: Saving pre-existing themes

How to apply Brand voice when generating courses

Brand voice

Asset library

Managing logos

How to create and configure themes

Managing and defaulting themes

Using the Brand kit

Brand Kit: A complete guide

How to edit video details

Brand kit

AI image generation

Generate a screen with AI

Refine with AI

Difference between transforming a document and converting a presentation

Coassemble's AI

Screens

Creating courses from scratch

Deleting courses

Duplicating courses

Enforce completion of videos

Generate a course with AI

The Finish screen

The Quiz screen

Transforming a document to a course

Translations

Images

Upload your videos to your course

Which screen should I use?

How do I create a course?

Common questions: Course creation

How to Upload Videos to Your Course

Narrating translations

Narration

Publishing

Loom integration

How to preview and review a course

Customizing course appearance with Themes

Managing and editing your course

Guide to AI Narration Tokens in Coassemble

Create & customize

Sharing course links & invitations

Collections: create, customize, share, and track learning paths

How to import a course from a template link

How to share your courses

Sharing courses with Slack

SCORM packages and translations

Exporting courses as SCORM

Common questions: Sharing

Template links

Email invitations

How to Add Your Coassemble Courses to Another Platform

How Coassemble tracks unique anonymous users

Sharing

How to filter Course insights by date range

Course insights

Link Insights

SCORM usage

Common Questions: Tracking Learners, Reporting, and Limits in Coassemble

Detailed Quiz results

Sentiment

Analyzing course-level Insights

Analyzing Collection-level Insights

Tracking content performance with Insights

Insights

Flow

Pulse

Embed Core

Embed Automate

Embed Partner

Overage, bands, and rates

Payments, billing, and subscriptions

Plans and advanced features

Explore best practices for sharing your knowledge.

Accessibility

Assessment: Best practice for quizzes

Coassemble is WCAG 2.2 Level AA Conformant

Best practices

SCORM files not loading

SCORM session errors on Apple devices

Why isn't my Embed screen working?

Common questions: Troubleshooting

What do I do if there is a bug?

Requesting a password reset link

Setting a new password

How to change or reset your password

Troubleshooting

SOC 2 compliance

Coassemble's approach to AI

AI & data security

Data security & AI

Upcoming plan changes

Updates and communication

Resources specifically for Embed (previously referred to as Headless course creation). These are resources that previously lived on the Headless Resources Hub.

Coassemble Embed Partner Security, Data Protection & AI FAQ

Default usage caps for clients

Managing tenant caps

Accessibility guide

AI and Data Security for Coassemble Embed Partners

Coassemble vs. Articulate: Feature comparison guide for course authoring teams

Competitor analysis

Designing effective microlearning courses

How to access and interpret the Headless usage report

How to handle competitor objections when positioning your Embed solution

Guide to pricing models for Coassemble Embed and key competitor benchmarks

Sales enablement guide: Driving user adoption

Customer testimonials for Coassemble Embed course creation (sales enablement)

Our mission: Barrier-free knowledge transfer (partner-friendly positioning language)

Passing identity (and tenant context) in embedded sessions

Share

Share

Passing identity (and tenant context) in embedded sessions

Share

Share