Skip to Content
Embed SystemSessions

Sessions

Embed sessions grant temporary, scoped access to Orderly for your end users. Every API call from an end user requires a valid session token (est_...).

Two Ways to Create Sessions

1. Manual Session (Backend-to-Backend)

Your backend creates a session with full control over scopes and constraints. This is the recommended approach — use an SDK or call the API directly.

Using the Node.js SDK:

import { Orderly } from '@orderly/node'
 
const orderly = new Orderly('oh_your-api-key')
 
const session = await orderly.embeds.createSession({
  externalId: 'customer_123',
  name: 'Acme Corp',
  email: 'acme@example.com',
  scopes: ['bridges:read', 'bridges:write', 'orders:read'],
  allowedBridgeTypes: ['shopify'],
  ttl: 3600,
})
 
// session.clientSecret → "est_..."

See the Node.js SDK and Java SDK docs for full details.

Using the REST API directly:

POST /api/embed/sessions
Authorization: Bearer oh_your-api-key
Content-Type: application/json
 
{
  "externalId": "customer_123",
  "name": "Acme Corp",
  "email": "acme@example.com",
  "scopes": ["bridges:read", "bridges:write", "orders:read"],
  "allowedBridgeTypes": ["shopify"],
  "ttlSeconds": 3600
}

Response:

{
  "data": {
    "token": "est_...",
    "sessionId": "uuid",
    "expiresAt": "2026-03-21T18:00:00Z",
    "scopes": ["bridges:read", "bridges:write", "orders:read"],
    "enabledFeatures": ["bridges", "data_room"],
    "endUser": {
      "id": "uuid",
      "externalId": "customer_123",
      "name": "Acme Corp",
      "email": "acme@example.com"
    }
  }
}

The externalId is your internal user identifier. If an end user with that ID doesn’t exist yet, Orderly creates one automatically.

2. Auto-Session (Publishable Key)

A simpler flow where sessions are created using just the publishable key. Scopes are automatically derived from your enabled features:

POST /api/embed/sessions/auto
Content-Type: application/json
 
{
  "key": "ek_your-publishable-key",
  "externalId": "customer_123",
  "name": "Acme Corp",
  "email": "acme@example.com"
}

Response:

{
  "data": {
    "token": "est_...",
    "expiresAt": "2026-03-21T18:00:00Z",
    "scopes": ["bridges:read", "bridges:write", "orders:read", "shipments:read"],
    "enabledFeatures": ["bridges", "data_room"]
  }
}

Auto-sessions validate the request Origin header against your configured allowed_origins.

Token Format

Session tokens follow the format est_ + 40 random characters. The token is returned once when created — Orderly stores only a bcrypt hash. If lost, create a new session.

Tokens are looked up by their prefix (first 12 characters) and verified against the stored hash.

Session Scoping

Each session is scoped to:

ScopeDescription
End UserThe session can only access resources belonging to this end user
PermissionsOnly the granted scopes are available
Bridge TypesOptionally restrict which bridge types can be created
TimeSessions expire after the configured TTL (default: 1 hour)

Revoking Sessions

DELETE /api/embed/sessions/:id
Authorization: Bearer oh_your-api-key

Revoked sessions immediately stop working. Use this when a user logs out of your application or you need to invalidate access.

Session Refresh

Sessions cannot be extended — create a new session when the current one expires.

The React and JavaScript SDKs handle this automatically. When a session is about to expire, the SDK calls your fetchClientSecret callback to get a fresh token and sends it to the embed via postMessage.

If you’re integrating without the SDKs, listen for the orderly:session.expiring postMessage event and respond with orderly:session.refresh containing the new token.

ConfigurationEnd Users