Configuration

Each organization has one embed config that controls all embed behavior. Creating or updating the config is done via the API using an oh_ API key with the embed:manage scope.

Creating Your Config


PATCH /api/embed/config
Authorization: Bearer oh_your-api-key
Content-Type: application/json
 
{
  "slug": "my-company",
  "allowed_origins": ["https://app.mycompany.com"],
  "allowed_bridge_types": ["shopify", "shipstation", "woocommerce"],
  "enabled_features": ["bridges", "data_room", "action_requests"],
  "branding": {
    "primaryColor": "#FF6B35",
    "backgroundColor": "#FFFFFF",
    "logoUrl": "https://mycompany.com/logo.png"
  },
  "settings": {
    "maxBridgesPerUser": 5,
    "webhookUrl": "https://mycompany.com/webhooks/orderly",
    "webhookSecret": "whsec_your-secret-key"
  }
}

This creates the config if it doesn’t exist, or updates it. The response includes your publishable key (ek_...), generated automatically on first creation.

Config Fields

Field	Type	Description
`slug`	string	Unique identifier for your embed (used in public config endpoint)
`allowed_origins`	string[]	Domains that can use your embed (validated on session creation)
`allowed_bridge_types`	string[]	Which bridge types end users can connect
`enabled_features`	string[]	Feature modules to enable (see below)
`branding`	object	Visual customization for embedded components
`settings`	object	Operational settings

Feature Modules

Enable features by including them in the enabled_features array:

Feature	Scopes Granted	Description
`bridges`	`bridges:read`, `bridges:write`	Always included. End users manage their own integrations.
`data_room`	`orders:read`, `shipments:read`, `tracking:read`	End users view their orders, shipments, and tracking.
`action_requests`	`actions:read`, `actions:write`	End users submit requests (cancel, hold, expedite).
`smart_alerts`	`alerts:read`, `alerts:write`	End users create alert rules and receive notifications.
`end_user_webhooks`	`webhooks:read`, `webhooks:write`	End users register their own webhook endpoints.
`branded_tracking`	`tracking:read`	Generate shareable branded tracking pages.

When a session is created via auto-session, the scopes are derived from whatever features are enabled.

Branding

Customize the appearance of embedded components:


{
  "branding": {
    "primaryColor": "#FF6B35",
    "backgroundColor": "#FFFFFF",
    "logoUrl": "https://mycompany.com/logo.png"
  }
}

Branding is returned with public config endpoints and branded tracking pages.

Publishable Key

Your publishable key (ek_...) is generated when you first create your embed config. It’s safe to include in frontend code — it identifies your organization but cannot access data on its own.

Use it for:

Auto-session creation (see Sessions)
Public config lookup


# Retrieve your config
GET /api/v1/embed/config/me
Authorization: Bearer oh_your-api-key

Allowed Origins

When configured, the embed middleware validates the Origin header on requests against your allowed_origins list. This prevents unauthorized domains from using your embed.


{
  "allowed_origins": [
    "https://app.mycompany.com",
    "https://staging.mycompany.com"
  ]
}

If allowed_origins is empty, origin validation is skipped.

Organization Webhook

The settings.webhookUrl receives server-side notifications when embed events occur (bridge connected, session created, etc.). Payloads are signed with settings.webhookSecret using HMAC-SHA256 in the X-Orderly-Signature header.

This is different from end user webhooks — this is your organization’s webhook for monitoring all embed activity.