Open in Iframe

This guide covers the full integration for displaying the OnBo dashboard inside your application with an <iframe>.

What you need from OnBo

Before you start, confirm you have:

Share your staging and production parent URLs with your OnBo contact during setup.

Integration flow

Your server                         Your web app                    OnBo dashboard (iframe)
     |                                     |                                    |
     |-- 1. Mint token (server-side) ----->|                                    |
     |<-- exchange token -------------------|                                    |
     |                                     |-- 2. Load iframe with SSO URL ---->|
     |                                     |                                    |-- 3. Sign-in completes
     |                                     |<-- 4. Dashboard displayed ----------|

1. Your backend calls the Mint API with the user’s credentials.
2. Mint returns a short-lived exchange token (valid for 120 seconds).
3. Your frontend loads an iframe with https://<dashboard-url>/sso?token=<exchange-token>.
4. OnBo completes sign-in inside the iframe and shows the dashboard.

Step 1 — Mint a token (server-side only)

Call the Mint API from your backend. Never call Mint from the browser or expose the mint secret to clients.

Endpoint

POST https://<dashboard-url>/api/embed/sso/mint

Headers

Authorization: Bearer <MINT_SECRET>
Content-Type: application/json

Request body

{
  "username": "user@example.com",
  "password": "user-password",
  "organizationId": "org_xxxxxxxx"
}

Success response (200)

{
  "token": "EXCHANGE_JWT",
  "expiresInSeconds": 120
}

Error responses

Example (curl)

curl -X POST "https://dashboard.example.com/api/embed/sso/mint" \
  -H "Authorization: Bearer $MINT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jane.doe",
    "password": "your-password",
    "organizationId": "org_abc123"
  }'

Mint a new token immediately before loading the iframe. Tokens are single-use and expire in 120 seconds.

Step 2 — Build the dashboard URL

Use the token from the Mint response:

https://<dashboard-url>/sso?token=<exchange-token>

Example:

https://dashboard.example.com/sso?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Pass this URL to your frontend over a secure channel (e.g. your own authenticated API). Do not hard-code tokens or reuse them across users.

Step 3 — Embed the iframe

<iframe
  id="onbo-dashboard"
  title="OnBo Dashboard"
  src="https://<dashboard-url>/sso?token=<exchange-token>"
  style="width: 100%; height: 100%; min-height: 720px; border: 0;"
  allow="clipboard-read; clipboard-write"
></iframe>

To set the URL after your page renders:

const iframe = document.getElementById("onbo-dashboard");
iframe.src = dashboardUrl; // from your backend, per user session

After sign-in, the iframe navigates to the dashboard internally. You do not need to update src again.

Recommended iframe settings

Security requirements

• Call Mint only from your server — the mint secret and user passwords must never reach the browser.
• Use HTTPS in production on your parent application.
• Generate a new exchange token per user session — tokens are single-use and short-lived.
• Do not log exchange tokens or share them between users.
• If you use Content-Security-Policy, allow the dashboard host in frame-src.

Browser testing

Test in the browsers your users use (Chrome, Safari, Firefox). Because the dashboard runs on a different domain, some browsers restrict cookies inside iframes.

Redirect fallback

If sign-in fails inside the iframe, open the same URL in the top-level window:

window.location.href = dashboardUrl;

The authentication flow is identical — only the container changes.

Troubleshooting

Mint returns 401

• Confirm the Authorization: Bearer <MINT_SECRET> header is present.
• Verify the mint secret matches what OnBo provided (no extra spaces or newlines).
• Confirm the username and password are correct for the OnBo account.
• Ensure password sign-in is enabled for the user.

Invalid or expired token in iframe

• Exchange tokens expire after 120 seconds — mint a fresh token before loading the iframe.
• Each token is single-use — do not reload the same SSO URL twice.

MFA or security step required

If the iframe shows a sign-in security error, the user may need to sign in once directly at the dashboard sign-in page, then retry the integration.

Blank or blocked iframe

• Your parent origin may not be allowlisted — confirm your domain with OnBo.
• Check that your CSP frame-src allows the dashboard host.

Session not persisting in iframe

• Some browsers block third-party cookies in iframes — test the redirect fallback.
• Prefer top-level redirect if iframe sign-in is unreliable for your users.

CORS errors when calling Mint

Call Mint from your backend only. Do not call Mint directly from the browser in production.

Getting help

When contacting OnBo support, include:

• Timestamp of the issue
• HTTP status codes (not raw tokens)
• Whether iframe or redirect was used
• Browser and parent application URL