Skip to Content
Embed SystemNode.js

Node.js SDK (@orderly/node)

Server-side SDK for creating embed sessions. Use this from your backend to generate scoped est_ tokens for your end users.

Installation

npm install @orderly/node

Quick Start

import { Orderly } from '@orderly/node'
 
const orderly = new Orderly('oh_your_secret_key')
 
const session = await orderly.embeds.createSession({
  externalId: 'user-123',
  name: 'Acme Corp',
})
 
// Pass session.clientSecret to your frontend
console.log(session.clientSecret) // est_...

Framework Examples

Next.js (App Router)

// app/api/orderly/session/route.ts
import { Orderly } from '@orderly/node'
import { auth } from '@/lib/auth'
 
const orderly = new Orderly(process.env.ORDERLY_API_KEY!)
 
export async function POST() {
  const user = await auth()
  if (!user) return Response.json({ error: 'Unauthorized' }, { status: 401 })
 
  const session = await orderly.embeds.createSession({
    externalId: user.id,
    name: user.company,
    email: user.email,
  })
 
  return Response.json({ clientSecret: session.clientSecret })
}

Express

import express from 'express'
import { Orderly } from '@orderly/node'
 
const app = express()
const orderly = new Orderly(process.env.ORDERLY_API_KEY!)
 
app.post('/api/orderly/session', async (req, res) => {
  const session = await orderly.embeds.createSession({
    externalId: req.user.id,
    name: req.user.company,
  })
 
  res.json({ clientSecret: session.clientSecret })
})

Hono

import { Hono } from 'hono'
import { Orderly } from '@orderly/node'
 
const app = new Hono()
const orderly = new Orderly(process.env.ORDERLY_API_KEY!)
 
app.post('/api/orderly/session', async (c) => {
  const user = c.get('user')
  const session = await orderly.embeds.createSession({
    externalId: user.id,
    name: user.company,
  })
 
  return c.json({ clientSecret: session.clientSecret })
})

API Reference

new Orderly(apiKey, options?)

ParameterTypeDescription
apiKeystringYour Orderly secret key (oh_...)
options.baseUrlstringAPI base URL (default: https://api.orderly.dev)

orderly.embeds.createSession(params)

Creates a session token for the embed.

ParameterTypeRequiredDescription
externalIdstringYesUnique user ID in your system
namestringNoDisplay name for the end user
emailstringNoEmail address
allowedBridgeTypesstring[]NoRestrict which bridge types are available
enabledFeaturesstring[]NoFeature modules to enable
scopesstring[]NoPermission scopes to grant
ttlnumberNoSession TTL in seconds (default: 3600)
metadataobjectNoCustom metadata to attach

Returns SessionResponse:

{
  clientSecret: string     // est_... token for the frontend
  sessionId: string        // Unique session ID
  expiresAt: string        // ISO 8601 expiration
  scopes: string[]         // Granted scopes
  enabledFeatures: string[] // Enabled features
  endUser: {
    externalId: string
    name?: string
    email?: string
  }
}

Error Handling

import { Orderly, OrderlyError } from '@orderly/node'
 
const orderly = new Orderly('oh_...')
 
try {
  const session = await orderly.embeds.createSession({
    externalId: 'user-123',
  })
} catch (err) {
  if (err instanceof OrderlyError) {
    console.error(`API error: ${err.message} (HTTP ${err.status})`)
  }
}
OverviewReact