SDKs

Orderly provides official SDKs for both server-side session creation and frontend embed rendering. The recommended pattern uses fetchClientSecret — your API key stays on your server, and the frontend receives a scoped session token.

Security Model


Your Server                      Orderly API                    Your Frontend
────────────                     ───────────                    ─────────────
orderly.embeds.createSession()   POST /api/embed/sessions
  (oh_ secret key)               → returns est_ token
  ← { clientSecret }
                                                                <OrderlyEmbed
                                                                  fetchClientSecret={...}
                                                                />
                                                                ↓
                                                                iframe + postMessage handshake
                                                                (token never in URL)

Your API key (oh_...) never leaves your server. The frontend SDK calls your server to get a short-lived est_ token, then passes it to the embed iframe via a secure postMessage handshake.

Available SDKs

Node.js (Server)

Create sessions from your backend. Works with Express, Next.js, Hono, etc.

React

Drop-in React component with automatic session management.

JavaScript

Vanilla JS for any framework. Also available via CDN script tag.

Java (Server)

Create sessions from Java backends. Spring Boot, Micronaut, etc.

Quick Example

1. Server — create a session endpoint:


import { Orderly } from '@orderly/node'
 
const orderly = new Orderly(process.env.ORDERLY_API_KEY)
 
// POST /api/orderly/session
export async function POST(req) {
  const session = await orderly.embeds.createSession({
    externalId: req.user.id,
    name: req.user.company,
  })
  return Response.json({ clientSecret: session.clientSecret })
}

2. Frontend — render the embed:


import { OrderlyEmbed } from '@orderly/embed-react'
 
function IntegrationsPage() {
  return (
    <OrderlyEmbed
      fetchClientSecret={() =>
        fetch('/api/orderly/session', { method: 'POST' })
          .then(r => r.json())
          .then(d => d.clientSecret)
      }
      appearance={{ primaryColor: '#6366f1' }}
      onBridgeCreated={(bridge) => console.log('Created:', bridge)}
    />
  )
}

Events

All frontend SDKs (React and JS) emit the same events:

Event	Callback	Description
Ready	`onReady`	Embed has loaded and is interactive
Bridge created	`onBridgeCreated`	End user connected a new bridge
Bridge updated	`onBridgeUpdated`	End user updated a bridge
Bridge deleted	`onBridgeDeleted`	End user removed a bridge
Error	`onError`	An error occurred in the embed

Session refresh is handled automatically — when a session is about to expire, the SDK calls fetchClientSecret again to get a fresh token.