Embedding a Reader

Add a Cirrus Reader instance to your site with the embed code generated in Studio, or initialise the reader yourself with JavaScript. Cirrus Reader instances using preAuth require a server-generated session token before the reader is initialised.

Embedding Flow

Create a reader instance

Configure the reader in Studio and choose the security level required by your integration.

Generate a token

For preAuth instances, call the token endpoint from your backend for the current user and publication.

Initialise the reader

Paste the Studio snippet into your page or construct the same options object manually.

Generate a preAuth Token (optional)

Call the token endpoint from your backend, never from the browser. Return only the generated token to your page and pass it to the reader as sessionToken.

Server side only

curl -X POST "https://api.cirrusreader.com/publication/token" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "reader-instance-id",
    "userId": "user-id",
    "publicationId": "publication-id"
  }'

Request Body

instanceIdRequired: The reader instance id from Studio or the Reader Instances API.
userIdRequired: Your stable identifier for the signed-in reader user. This is used for the reader session and reading state.
publicationIdRequired: The publication id when your integration tracks publications by id.
usesInternalStorageOptional: Set only when the publication should be authorised against internal storage.

Response

{
  "requestId": "request-id",
  "token": "reader-session-token"
}

Generate Embed Code in Studio

Studio can generate a complete snippet for an existing reader instance. Use this path when you want the application to keep the script URL, instance id, origin, and config version aligned with the selected reader instance.

Open Studio and go to Reader Config.
Create or select the reader instance you want to embed.
Open the row actions menu and choose Embed.
Copy the generated embed snippet into the page where the reader should appear.
If the instance requires preAuth, generate the token on your backend and replace YOUR_PRE_AUTHENTICATION_TOKEN before initialising the reader.

Manual JavaScript Schema

If you are building your own integration, load the reader script and create a window.CirrusReader instance with the options below.

Embed example

<div id="cirrus-reader" style="width: 100%; min-height: 600px;"></div>
<script src="https://app.cirrusreader.com/cirrus-reader-1.0.0.min.js?BUILD_ID" defer></script>
<script type="text/javascript">
async function initialiseCirrus() {
  const userId = "user-id";
  const publicationId = "publication-id";

  if (!publicationId) {
    console.error("Missing required publicationId")
    return
  }

  const configurationId = "reader-instance-updated-at-iso";
  const container=document.getElementById("cirrus-reader");
  if(!container||!window.CirrusReader)return;const reader=new window.CirrusReader({instanceId:"reader-instance-id",configVersion:configurationId,container,sessionToken:'YOUR_PRE_AUTHENTICATION_TOKEN',config:{user:userId ?? undefined,publication:{id:publicationId}}});reader.initialise();
}

window.addEventListener("DOMContentLoaded", initialiseCirrus);
</script>

Options schema

type CirrusReaderConstructorOptions = {
  instanceId: string
  origin?: string
  configVersion?: string
  container: Element
  sessionToken?: string | null
  config?: {
    user: string
    publication: {
      id: string
    }
    theme?: string | object
    themes?: object[]
    sessionToken?: string | null
    [key: string]: unknown
  }
}

Security Notes

Keep API keys off the client

The token request uses your API key. Make the request from a trusted backend and expose only your own session endpoint to the browser.

Match tokens to the active reader

Generate each token for the reader instance, user, and publication that will be loaded. Do not reuse a token across unrelated readers or users.