Agent Console

1. Get your REST API key

As a Surfly company admin, open the Surfly dashboard → Company → API, generate a key, and store it as a server-side secret (env var, secret manager, etc). Treat it like a password — anyone with this key can mint tokens for any agent in your company.

2. Backend: mint a token per agent

When a signed-in agent loads the page that should host the Surfly widgets, your backend calls Surfly's REST API and returns just the agent_token to the browser.

// Node / Express
app.get('/api/surfly-token', requireAuth, async (req, res) => {
  const r = await fetch(
    `https://surfly.com/v2/agents/access-token/?api_key=${process.env.SURFLY_KEY}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        // Identify by existing Surfly agent…
        agent_id: req.user.surflyAgentId,
        // …or auto-provision from your identity system:
        // email: req.user.email,
        // name:  req.user.name,
        // role:  'agent', // 'admin' | 'manager' | 'agent'
      }),
    }
  );
  const { agent_token, expires_in, agent_role } = await r.json();
  res.json({ agent_token, expires_in, agent_role });
});

3. Frontend: embed the iframes

Fetch the token from your backend, then drop it into the iframe src. Keep theallow attribute exactly as below — Surfly needs camera, mic and screen-share permissions.

<iframe
  width="1024"
  height="768"
  src="https://app.surfly.com/embed/queue/?agent_token=THE_TOKEN"
  allow="autoplay *; camera *; microphone *; display-capture *; geolocation *;">
</iframe>

Paths: start, queue,history, options. Render tabs/links in your own UI and grey-out the ones the agent's role can't access (Surfly enforces it server-side either way).

4. SSO users: an alternate auth path for the Start Page

There are two ways the embedded iframe can authenticate the agent:

• Token flow (steps 2–3 above): always works. Your backend mints anagent_token and the iframe URL carries it.
• SSO cookie flow: if your company has Surfly SSO set up and the agent has already signed in to app.surfly.com via SSO in the same browser, the iframe can authenticate from the existing Surfly session cookie. No token in the URL.

The SSO variant looks like this:

<iframe src="https://app.surfly.com/embed/start/sso/" allow="…"></iframe>

Things to know before picking the SSO path:

• Start Page only. There is no /embed/queue/sso/ or equivalent — Queue, History and Options still go through the token flow. So picking SSO for Start gives you a hybrid (SSO for Start, tokens for the rest), which is usually more complex than just using tokens everywhere.
• Requires an existing Surfly SSO session. If the agent opens your app in an incognito window, a different browser, or just hasn't logged in to Surfly yet, the iframe will redirect to the SSO login wall instead of rendering.
• Role comes from the Surfly user record, mapped from SSO attributes — you don't pass it from your code.
• SSO must be configured first in the Surfly admin (SAML/OIDC + role mapping) before any of this is usable.

Practical recommendation: default to the token flow for all four widgets — it's one code path and works regardless of how the agent is authenticated. Reach for the SSO Start URL when you specifically want a low-setup proof-of-concept embedding just the Start Page and you can rely on the agent already being SSO'd in.

You can try the SSO Start Page from this demo by toggling Use SSO for Start Page in the configuration panel below — works only if you're already signed in to app.surfly.com in this browser.

5. Token lifecycle & refresh

• Tokens expire 24 hours after first issue.
• Simplest pattern: fetch a fresh token from your backend on every page load.
• For long-lived SPA sessions, refresh just before expires_in elapses, or lazily on a 401 from the iframe.
• The same agent_token also lets an agent join a private co-browse session via ?agent_token=… on the session URL — no Surfly login needed.

What to copy from this demo, and what NOT to copy

• Copy: iframe URLs, allow attribute, role-aware tab gating UX.
• Don't copy: sending the REST API key from the browser. Real integrations keep it on the server.