Embedding Hyphen

Hyphen supports three integration modes:

Gateway mode for most SaaS and browser-facing products
Direct engine mode for private deployments and low-level backend integration
SDK mode for embedded browser surfaces

Mode A: Gateway

Use Hyphen Gateway as your public edge.

Gateway responsibilities:

API key auth
management token auth
publishable-key auth for browser surfaces
tenant resolution and upstream header injection
rate limiting and usage logging
browser-safe delivery of SDK-backed surfaces
hosted pages that need no build on your side: the Process Studio catalog at /process-studio/v5.html and public forms at /forms/<formId>

Onboarding flow

Create account:

bash

curl -X POST https://your-hyphen.example.com/gateway/signup   -H "Content-Type: application/json"   -d '{
    "email": "ops@acme.com",
    "name": "Acme Ops"
  }'

Save returned credentials:

management token for admin and org management
API key for runtime calls

Manage orgs and keys with the management token.
Call runtime APIs through the gateway with the API key.

The gateway strips the key before forwarding and injects tenant context for the engine.

Mode B: Direct engine

Use direct engine mode for backend integrations inside a private Hyphen deployment. Keep the endpoint within the access boundary defined for that deployment.

Every tenant-scoped request includes X-Org-Id as organization context. Add the access headers required by your deployment.

bash

curl -X POST https://your-onprem-domain/workflows/:id/execute   -H "X-Org-Id: acme-corp"   -H "Content-Type: application/json"   -d '{
    "input": {
      "customer_id": "cust_123"
    }
  }'

Mode C: SDK

For teams that want browser-safe operational surfaces without building them from scratch, use the SDK.

Load the gateway-hosted browser bundle:

html

<script src="https://your-hyphen.example.com/sdk/v1.js"></script>

<script>
  const sdk = await HyphenSDK.init({
    publishableKey: 'pk_live_your_key_here',
    baseUrl: 'https://your-hyphen.example.com'
  });
</script>

Then embed the surfaces you need:

html

<hyphen-task-sidebar auto-refresh></hyphen-task-sidebar>
<hyphen-data-grid table="invoices" editable></hyphen-data-grid>
<hyphen-doc-feed workflow-id="wf_invoice_processing" accept=".csv,.pdf"></hyphen-doc-feed>

The SDK authenticates with a publishable key. Organization context is resolved server-side from that key. The browser never sends X-Org-Id directly.

Forms

Intake forms and paused-step forms render with the same bundle:

html

<hyphen-form-button form-id="frm-…" public>Dispute a charge</hyphen-form-button>
<hyphen-form run-id="run-…" step-id="2"></hyphen-form>

A page with no publishable key can still render public forms by calling HyphenSDK.defineFormElements() instead of init(). Attributes, events, and the hosted page are on the Forms page; the walkthrough is Forms that start work.

Process Studio

The catalog and case screens embed as one element:

html

<hyphen-process-studio-v5 target-org-id="org_…"></hyphen-process-studio-v5>

See Process Studio and the component reference.

See:

Choosing the right mode

If you need...	Recommended mode
public SaaS runtime access	Gateway
browser-safe embedded surfaces	SDK
low-level private runtime access	Direct engine

Approval UX integration

If you build your own approval UI instead of using the SDK, submit reviewer decisions directly:

bash

curl -X POST https://your-hyphen.example.com/approvals/:runId/:stepId   -H "X-Org-Id: acme-corp"   -H "Content-Type: application/json"   -d '{
    "approved": true,
    "comment": "Looks good"
  }'

Webhook contract

Webhook body format:

json

{
  "event": "pbot_approval_requested",
  "timestamp": "2026-03-03T10:30:00.000Z",
  "payload": {
    "run_id": "run-...",
    "step_id": "2",
    "comment": "Review required"
  }
}