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

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 when deploying Hyphen privately or when you want low-level runtime integration without the public gateway.

Every tenant-scoped request must include X-Org-Id.

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.

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"
  }
}