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, shared by every session on the key

Budget your requests

The rate limit is per publishable key and per minute, and every browser session on the key draws from the same budget. When it is exceeded the gateway answers 429 with a Retry-After header; the SDK waits and retries reads on its own, so a busy page slows down rather than breaks.

What a page costs: while a run is followed, one status poll every few seconds, backing off to one every ten; one refresh of the task sidebar per burst of task events. Keep the event stream open rather than polling, use one key per surface, and raise the limit on a key that many people share. The key's limit is set when you create it and can be changed later through the same management API.

Public form pages have their own limits by visitor IP: 60 reads and 10 submits per form 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