Embed SDK

Embed the agent shared inbox inside your own product (ERP, admin portal, shop backend).

Audience: partner developers connecting another app to a SupportCaptain workspace.
Live SDK: https://supportcaptain.com/sdk/v1/supportcaptain.js
Public guide: https://supportcaptain.com/docs/embed

What you get

• Full HelpScout-style shared inbox (folders, reply, notes, attachments) inside your UI
• Agents identified by email (same address in your app and SupportCaptain)
• Secure short-lived JWT (never put the embed secret in the browser)
• Works in Safari / cross-site iframes (API auth via Bearer JWT, not third-party cookies alone)
• Open full app with auto-login via handoff URL

Architecture

Your app (agent logged in)
    │
    ├─ Frontend: SupportCaptain.init({ getToken })
    │       └─ iframe → https://supportcaptain.com/embed/mailbox?token=JWT
    │
    └─ Backend: POST /api/embed/sessions
            Authorization: Bearer emb_…
            body: { "email": "agent@firma.dk" }
                    │
                    ▼
            SupportCaptain validates secret + finds workspace member
            returns { token, embed_url, user }

Inside the iframe, the SPA calls /api/* with:

Authorization: Bearer <same embed JWT>

so API calls work even when browsers block third-party session cookies.

1. Enable embed (workspace admin)

In SupportCaptain (full app):

1. Open Settings → Embed SDK

2. Enable embed

3. Add allowed origins (exact scheme + host, no path), e.g.
   https://app.yourproduct.com
https://admin.firma.dk

4. Copy:

   • Public key ws_… → safe in frontend
   • Secret emb_… → server only

5. Ensure every agent who will open the embed exists as an active user in this workspace with the same email as in the partner app.

Tip: invite teammates under Settings → Team first, then connect embed.

2. Mint a session token (your backend)

Never call this from browser JavaScript with the secret.

POST https://supportcaptain.com/api/embed/sessions
Authorization: Bearer emb_YOUR_SECRET
Content-Type: application/json
Accept: application/json

{
  "email": "agent@firma.dk",
  "ttl": 900,
  "view": "unassigned"
}

Success (201):

{
  "token": "eyJ…",
  "expires_in": 900,
  "expires_at": "2026-07-18T14:00:00+00:00",
  "embed_url": "https://supportcaptain.com/embed/mailbox?token=eyJ…&view=unassigned",
  "user": { "id": 42, "name": "Anne Agent", "email": "agent@firma.dk" }
}

Common errors

Example (PHP)

$ch = curl_init('https://supportcaptain.com/api/embed/sessions');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $embedSecret,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'email' => $loggedInAgentEmail,
        'view'  => 'unassigned',
        'ttl'   => 900,
    ]),
]);
$data = json_decode(curl_exec($ch), true);
// return $data to your frontend (token only — never the emb_ secret)

3. Frontend: drop-in SDK

<div id="support-captain" style="height:100vh;min-height:640px;"></div>
<script src="https://supportcaptain.com/sdk/v1/supportcaptain.js"></script>
<script>
  let sc;

  async function mintFromYourBackend() {
    const r = await fetch('/api/your-app/sc-embed-token', { credentials: 'include' });
    if (!r.ok) throw new Error('Mint failed');
    return r.json(); // { token } or full mint response
  }

  async function mount() {
    if (window.SupportCaptain?.destroy) SupportCaptain.destroy();
    sc = await SupportCaptain.init({
      workspaceKey: 'ws_…',           // public key from Settings → Embed
      appUrl: 'https://supportcaptain.com',
      target: '#support-captain',
      view: 'unassigned',
      height: '100%',
      getToken: mintFromYourBackend,
      onEvent: (type, payload) => {
        if (type === 'sc:auth-expired') {
          // Remint and remount (do NOT full-page reload in a tight loop)
          mount().catch(console.error);
        }
        if (type === 'sc:thread-open') {
          console.log('Opened thread', payload.threadId);
        }
      },
    });
  }

  mount().catch(console.error);
</script>

Host page requirements

CSP (if you set Content-Security-Policy)

Allow the SDK script and iframe:

script-src … https://supportcaptain.com;
frame-src  … https://supportcaptain.com;
connect-src … https://supportcaptain.com;

Do not set X-Frame-Options on pages that only host the partner app (your site frames SC; SC does not need to frame you).

4. SDK reference

SupportCaptain.init(options) → Promise<{ destroy, openThread, setView, iframe }>

* One of getToken or token is required.

Methods

Events (onEvent / postMessage from iframe)

Host → iframe messages use source: 'supportcaptain-host'.
Iframe → host messages use source: 'supportcaptain'.

5. Open full app (auto-login)

Do not link bare https://supportcaptain.com/mailbox (no session).

Mint a token, then open handoff in a new top-level tab (first-party cookies):

const { token } = await mintFromYourBackend();
const u = new URL('https://supportcaptain.com/embed/handoff');
u.searchParams.set('token', token);
u.searchParams.set('view', 'unassigned');
window.open(u.toString(), '_blank', 'noopener');

Handoff verifies the JWT, logs the agent in, and redirects to /mailbox.

6. Agent matching & multi-product setup

Recommended onboarding for a new customer

1. Create SupportCaptain workspace
2. Connect Microsoft 365 mailbox(es)
3. Invite agents (email = their login in your product)
4. Settings → Embed → enable + add your product origin(s)
5. Store ws_… + emb_… in your product settings (encrypted)
6. Embed page mints with the current agent’s email

One SupportCaptain workspace can be connected from multiple partner products (add every origin).
Each partner product stores its own copy of the keys (or you rotate secrets per environment).

7. Security checklist

• emb_… only on the server
• Allowed origins exact match (https://host — no trailing path)
• Tokens short-lived (≤ 15 minutes default)
• HTTPS everywhere
• Agents deactivated in SC when they leave the company
• Rotate secret if a server is compromised

8. Troubleshooting

9. Reference URLs

Related

• CRM Context Integration — show orders/contacts from your ERP in the SC sidebar
• REST API — broader API access
• Brugermanual — end-user features