Hosted integration

Your server exchanges a mint secret for a signed launch link. Your website then shows a link or a compact launch card. The full lab experience runs on Hosted Lab Pages. The mint API is separate from the organization REST API.

Create a launch link

The hosted mint route is POST /launch/api/mint. Use the full endpoint URL from onboarding. Every request includes the X-Mint-Secret header and a JSON body:

{
  "labId": "lab_id",
  "learnerId": "academy:user:uuid",
  "membership": "free",
  "displayName": "Learner"
}

Request fields

Field	Required	Meaning
`labId`	Yes	The lab to open
`learnerId`	No	Stable learner ID from your server session
`membership`	No	`free` or `premium`, defaults to `free`
`displayName`	No	Public name for discussions, up to 80 characters
`memberId`	No	Optional member identifier for configured survey attribution

The server chooses membership from your access policy. Premium lab access requires membership: "premium". An absent or unrecognized value becomes free. The mint route normalizes displayName and removes control characters. It does not derive a public name from learnerId. memberId accepts 1–64 letters, numbers, underscores, or hyphens. Invalid values are ignored. This field does not replace learnerId.

Learner identity

A supplied learner ID stays the same across launches. It can identify a signed-in learner or a guest session managed by your platform. Without an ID, Cybr generates a new anon: identity for that mint request. The response includes the generated ID. Completion is recorded against that anonymous ID. A later mint without an ID creates a different learner identity and does not retain the previous completion. Automatically generated anonymous identities cannot post or delete discussion comments.

Response

A successful request returns HTTP 200:

{
  "token": "signed-launch-token",
  "url": "https://labs.cybr.com/launch?token=...",
  "embedUrl": "https://labs.cybr.com/launch/embed?token=...",
  "expiresAt": "2026-10-01T12:00:00.000Z",
  "learnerId": "academy:user:uuid"
}

Field	Meaning
`token`	Signed authorization for this launch link
`url`	Full hosted lab page
`embedUrl`	Compact launch card for an iframe
`expiresAt`	Launch-token expiration timestamp
`learnerId`	Supplied or generated learner ID

A signed URL grants access to the associated learner’s lab session. Return it only to that learner.

Server example

mintEndpoint and mintSecret come from secure server configuration. learnerId and membership come from your server session and access policy.

async function mintLaunch({ labId, learnerId, membership, displayName }) {
  const response = await fetch(mintEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Mint-Secret': mintSecret
    },
    body: JSON.stringify({ labId, learnerId, membership, displayName })
  })

  if (!response.ok) {
    const detail = await response.json().catch(() => ({}))
    throw new Error(detail.error || `Mint failed: ${response.status}`)
  }

  return response.json()
}

The mint secret authorizes requests for your organization. It does not belong in browser code, source control, or logs.

Mint errors

HTTP status	Meaning	Next action
`400`	Missing lab ID or invalid input	Correct the request
`401`	Missing or invalid mint secret	Check server configuration
`403` or `404`	Lab lookup denied or lab unavailable	Check the lab ID and organization access
`429`	Mint request limit reached	Wait for `retryAfter` seconds
`5xx`	Hosted service or upstream request failed	Show an error and handle retries

A rate-limit response includes retryAfter in the JSON body and a Retry-After header. Named learners and generated anonymous identities use separate mint limits. Mint limits are separate from deployment launch limits. A successful mint does not reserve a deployment slot or guarantee a successful launch.

Show a link or launch card

Direct link

Set the link target to url from the mint response:

<a href="https://labs.cybr.com/launch?token=..." target="_blank" rel="noopener">
  Open lab
</a>

This opens the full hosted page. It does not add a completion listener to your website.

Embedded card

Set an iframe source to embedUrl:

<iframe
  id="cybr-lab"
  title="Cybr lab launch card"
  src="https://labs.cybr.com/launch/embed?token=..."
  style="width: 100%; height: 320px; border: 0;"
></iframe>

The iframe contains a compact launch card. Its button opens the full lab page in a new tab. Cybr must allow your embedding origin. An origin includes the scheme and host, such as https://learn.example.com, without a page path. The iframe height is an example. Your page can adjust it to fit the card’s content.

Dark card

The compact card accepts theme=dark:

const cardUrl = new URL(embedUrl)
cardUrl.searchParams.set('theme', 'dark')
document.getElementById('cybr-lab').src = cardUrl.toString()

This parameter controls the compact card. It is separate from the full player’s theme and your organization’s branding arrangements.

Completion notifications

The embedded card sends this message to an allowed parent origin:

{ "type": "cybr:lab-completed", "labId": "lab_id" }

A correct CTF flag records completion. The hosted page also supports explicit completion for other lab experiences. The card checks stored completion and can send the message again after a reload. The event does not identify a new attempt or verification method. Register a listener on the page that contains the iframe:

const frame = document.getElementById('cybr-lab')
const hostedOrigin = 'https://labs.cybr.com'

window.addEventListener('message', (event) => {
  if (event.origin !== hostedOrigin) return
  if (event.source !== frame.contentWindow) return
  if (event.data?.type !== 'cybr:lab-completed') return
  if (event.data.labId !== expectedLabId) return

  showLessonCompleted(expectedLabId)
})

expectedLabId and showLessonCompleted belong to your application. If the hosted origin differs from the example, use the origin from onboarding. The message is a browser notification, not a server webhook. Your server can read learner completion through the organization API before it updates trusted records. That API request uses an organization API key, not the mint secret. A direct link does not provide the embedded-card relay. Direct-link integrations can read completion through the API instead.

Link expiration and reuse

A launch token expires after two hours by default. Hosted configuration can change that duration. The response’s expiresAt is the exact deadline. Each signed link can start at most one deployment. A reload can restore the existing session, but a new deployment requires a new link. A second launch with a spent link returns 409 with code: "link_used". A failed launch releases the link reservation for another attempt. After the lab ends, obtain a fresh link for a new attempt. After token expiration, obtain a fresh link before opening the lab page again.

End notification

The embedded card can relay an end event:

{ "type": "cybr:lab-ended", "labId": "lab_id", "reason": "destroyed" }

Reasons include destroyed, timeUp, expired, linkUsed, and failed after a deployment spent the link. Your page can obtain a fresh link after this event. Use the same origin, iframe-source, and lab-ID checks as the completion listener. End-event delivery is best effort. Your interface must also offer a way to request a fresh link without that event. Ending or expiring a lab does not itself record learner completion.

Before going live

Complete these checks:

Store the mint secret in secure server configuration.
Check your lab IDs and learner access policy.
Send Cybr the exact origins that will embed the card.
Launch a lab with both free and premium access where applicable.
If your platform supports guests, check guest identity behavior.
Complete a lab and check your platform’s progress update.
End a lab and obtain a fresh link for another attempt.

For setup questions, contact support@cybr.com.

​Create a launch link

​Request fields

​Learner identity

​Response

​Server example

​Mint errors

​Show a link or launch card

​Direct link

​Embedded card

​Dark card

​Completion notifications

​Link expiration and reuse

​End notification

​Before going live