SDK Quickstart

Time: ~10 minutes | Prerequisites: A Hyphen account with at least one workflow or surface to expose

1. Get a publishable key

Publishable keys are created by your org admin via the gateway management API.

bash
curl -X POST https://your-hyphen.example.com/sdk/admin/publishable-keys   -H "Authorization: Bearer mt-hyp-..."   -H "Content-Type: application/json"   -d '{
    "label": "ops-dashboard",
    "allowed_origins": ["https://internal.acme.com"],
    "allowed_tables": ["invoices", "payments"],
    "allowed_workflows": ["wf_invoice_processing"]
  }'

Save the returned pk_live_* key. This key is safe to include in client-side code — it cannot modify workflows, access admin endpoints, or perform actions outside its configured scope.

Key scoping

Each publishable key is restricted to:

Scope Description
Allowed origins Which domains can use this key
Allowed workflows Which workflows are visible through SDK components
Allowed tables Which custom tables are accessible in the data grid
Allowed actions Which actions can be triggered
Rate limit Requests per minute

2. Add the SDK to your page

Use the gateway-hosted bundle:

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

If you run your own gateway host, use the same path on your host.

Initialize the SDK:

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

The SDK creates an anonymous session scoped to your publishable key. That is enough for many embedded operational surfaces.

3. Embed a surface

Task sidebar

html
<hyphen-task-sidebar auto-refresh show-urgency></hyphen-task-sidebar>

Data grid

html
<hyphen-data-grid table="invoices" editable highlight-agent></hyphen-data-grid>

Document feed

html
<hyphen-doc-feed workflow-id="wf_invoice_processing" accept=".pdf,.csv,.xlsx"></hyphen-doc-feed>

4. Enable authentication (optional)

For user-level audit trails and per-user permissions, enable OTP authentication:

javascript
const sdk = await HyphenSDK.init({
  publishableKey: 'pk_live_...',
  baseUrl: 'https://your-hyphen.example.com',
  onSessionExpired: () => sdk.login()
});

document.querySelector('#login-btn').addEventListener('click', () => {
  sdk.login();
});

Users must be added in advance by an org admin against the publishable key before they can authenticate.

5. Enable real-time updates (optional)

javascript
sdk.startEventStream();

sdk.on('task:created', (e) => {
  console.log('New task:', e.data);
});

Next steps