SDK Quickstart

Time: ~10 minutes | Prerequisites: A Hyphen account with at least one workflow

1. Get a Publishable Key

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

bash
curl -X POST https://apisvr.tryhyphen.com/gateway/orgs/:orgId/sdk-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 (CORS enforcement)
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 (default: 60)

2. Add the SDK to Your Page

Include the script tag in your HTML:

html
<script src="https://cdn.tryhyphen.com/sdk/v1.js"></script>

Initialize the SDK:

html
<script>
  (async () => {
    const sdk = await HyphenSDK.init({
      publishableKey: 'pk_live_your_key_here'
    });
  })();
</script>

The SDK creates an anonymous session scoped to your publishable key. This is sufficient for read-only dashboards and task views.

3. Embed Components

Task Sidebar

Show pending approval tasks from your workflows:

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

Data Grid

Display a sortable, paginated data table with inline editing:

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

Document Feed

Let your team upload files that trigger workflow runs:

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_...',
  onSessionExpired: () => sdk.login()
});

// Show the login modal when the user clicks a button
document.querySelector('#login-btn').addEventListener('click', () => {
  sdk.login();
});

Users must be pre-registered by an org admin against the publishable key before they can authenticate. The SDK does not support self-registration.

5. Enable Real-Time Updates (Optional)

Start the server-sent event stream for live updates across all components:

javascript
sdk.startEventStream();

// Components automatically update when events arrive
sdk.on('task:created', (e) => {
  console.log('New task:', e.data);
});

Complete Example

html
<!DOCTYPE html>
<html>
<head>
  <title>Ops Console</title>
  <script src="https://cdn.tryhyphen.com/sdk/v1.js"></script>
</head>
<body>
  <div style="display: flex; height: 100vh;">
    <!-- Task sidebar on the left -->
    <hyphen-task-sidebar auto-refresh show-urgency
      style="width: 360px; border-right: 1px solid #e5e5e5;">
    </hyphen-task-sidebar>

    <!-- Main content area -->
    <div style="flex: 1; padding: 24px;">
      <h1>Invoices</h1>
      <hyphen-data-grid table="invoices" editable highlight-agent>
      </hyphen-data-grid>

      <h2 style="margin-top: 32px;">Upload Documents</h2>
      <hyphen-doc-feed workflow-id="wf_invoice_processing"
        accept=".pdf,.csv,.xlsx">
      </hyphen-doc-feed>
    </div>
  </div>

  <script>
    (async () => {
      const sdk = await HyphenSDK.init({
        publishableKey: 'pk_live_your_key_here',
        onSessionExpired: () => sdk.login()
      });

      // Optional: enable real-time updates
      sdk.startEventStream();

      // Listen for events
      sdk.on('task:decided', (e) => {
        console.log('Task decided:', e.data);
      });
    })();
  </script>
</body>
</html>

Next Steps

  • Components — full attribute and event reference for all four components
  • Authentication — anonymous vs. authenticated sessions, OTP flow
  • Theming — match your brand with CSS custom properties
  • Events — real-time event system and cross-component updates