Skip to main content

White-label embed portal

The embed lets your customers connect their own integrations, under your brand, inside your app. You issue a short-lived session for each end user, and they see a branded "Integrations" surface where they connect their own Shopify or other platforms. Manage it under Embed.

Activate the embed​

On the Embed page, choose a slug (like my-company) and click Create. Add every customer application origin under Embed → Settings, choose the permitted bridge types and features, and then activate Embed.

Embed it in your app​

The setup card provides ready-to-copy snippets for React, JavaScript, and your server. Your authenticated backend mints a session and the SDK supplies its client secret to the iframe through a postMessage handshake.

See the Orderly Embed SDK guide for package installation, complete options, events, and Java support.

  1. On your server, create a session for the signed-in customer:

    import { Orderly } from '@orderly/node'

    const orderly = new Orderly(process.env.ORDERLY_API_KEY)

    app.post('/api/orderly/embed-session', requireUser, async (req, res) => {
      const session = await orderly.embeds.createSession({
        externalId: req.user.id,
        name: req.user.companyName,
        scopes: ['bridges:read', 'bridges:write'],
        ttlSeconds: 900,
      })

      res.set('Cache-Control', 'no-store')
      res.json({ clientSecret: session.clientSecret })
    })

  2. In your frontend, render the embed with that secret:

    import { OrderlyEmbed } from '@orderly/embed-react'

    export function Integrations() {
      return (
        <OrderlyEmbed
          fetchClientSecret={() =>
            fetch('/api/orderly/embed-session', {
              method: 'POST',
              credentials: 'same-origin',
            })
              .then((response) => response.json())
              .then((data) => data.clientSecret)
          }
        />
      )
    }

Never accept the end-user identifier from the session-creation request body. Derive it from your authenticated application session. Orderly secret API keys remain server-only, and client secrets must not be logged, persisted, or placed in URLs.

The ek_ publishable key can identify public branding configuration, but it cannot create an embed session or authorize access to an end user's data.

End users are created for you

You do not invite embed users by hand. An end user is provisioned automatically the first time your server calls createSession for their externalId. The Users page lists them and the bridges each has connected.

Brand it​

Under Embed → Branding, set your Primary, Background, and Text colors, Font Family, Border Radius, and an HTTPS Logo URL. The preview updates as you edit. Click Save Changes before testing through your SDK integration.

Configure what customers can do​

Under Embed → Settings:

  • Feature Modules toggles what the embed exposes: Bridges (always on), Live Data Room, Action Requests, Smart Alerts, End User Webhooks, and Branded Tracking.
  • Allowed Origins is mandatory for active embeds. Enter exact origins such as https://app.example.com; paths and wildcard domains are not accepted.
  • Allowed Bridge Types limits which platforms customers can connect.
  • Default Dispatcher auto-routes orders from embed-created bridges.
  • Limits caps bridges per user.

Handle action requests​

If you enable Action Requests, your customers can submit requests against their orders (cancel, hold, expedite). They land in Embed → Action Requests as a review queue. Filter by status, then Approve or Deny each, with an optional resolution note.

The Events page is an audit log of embed activity: sessions created and revoked, bridges connected, and users removed.

Security model​

  • Each est_ client secret is short-lived, belongs to one organization and one end user, and contains only server-approved scopes and bridge types.
  • Disabled end users, revoked sessions, expired sessions, inactive embed configurations, and unlisted parent origins fail closed.
  • The browser cannot exchange a publishable key or choose an externalId to create a session.
  • Use a dedicated API key with the embed:manage scope for session issuance.
  • Issue a new client secret when fetchClientSecret is called. Do not reuse one client secret between users or browser sessions.

Next steps​