Authentication

The SDK supports two session modes: anonymous (default) and authenticated (OTP). Both are scoped to your publishable key's permissions.

Anonymous Sessions

When you call HyphenSDK.init(), the SDK creates an anonymous session:

javascript
const sdk = await HyphenSDK.init({
  publishableKey: 'pk_live_...'
});

sdk.isAuthenticated(); // false
sdk.getUser();         // null

Anonymous sessions are sufficient for:

  • Read-only dashboards
  • Viewing pending tasks
  • Browsing data tables (without editing)

All actions in anonymous sessions are logged with the session ID but without a user identity.

Authenticated Sessions (OTP)

For user-level audit trails, per-user permissions, and edit access, enable OTP authentication.

Login Flow

javascript
// Show the login modal
sdk.login();

The modal guides the user through:

  1. Email entry — the user enters their registered email
  2. Code verification — the user enters the 8-digit OTP sent to their email
  3. Success — the session is upgraded and the modal auto-closes
javascript
// Listen for successful authentication
sdk.on('authenticated', (e) => {
  console.log('Signed in as:', e.data.email);
});

Pre-Registration Requirement

Users must be added to your publishable key's allowed user list before they can authenticate. The SDK does not support self-registration or open signup.

Add users via the gateway management API:

bash
curl -X POST https://apisvr.tryhyphen.com/gateway/orgs/:orgId/sdk-keys/:keyId/users \
  -H "Authorization: Bearer mt-hyp-..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "reviewer"
  }'

Session Lifecycle

Token Expiry

Session tokens have a fixed time-to-live. When a session expires, the SDK emits a session:expired event:

javascript
const sdk = await HyphenSDK.init({
  publishableKey: 'pk_live_...',
  onSessionExpired: () => {
    // Prompt re-authentication
    sdk.login();
  }
});

Checking Session State

javascript
sdk.isAuthenticated();  // true if OTP-verified
sdk.getSession();       // { sessionId, expiresAt, ... }
sdk.getUser();          // { email, role } or null

Logout

javascript
sdk.logout();  // Clears session, reverts to anonymous

After logout, all components revert to anonymous-level access. The task sidebar may show fewer tasks, and editable grids become read-only (depending on your publishable key's anonymous permissions).

Security Model

Property Detail
Origin binding Publishable keys are restricted to configured domains (CORS enforcement)
Session tokens Short-lived, non-renewable
OTP codes Expire after 10 minutes; locked out after 5 failed attempts
Org resolution Server-side from publishable key — the SDK never sends X-Org-Id
Audit logging Every action is logged with session identity (anonymous or authenticated user)
Shadow DOM isolation Components are isolated from host page scripts — no DOM access to internal state

Publishable keys are not secret. They are designed for client-side use. Security is enforced server-side through origin restrictions, scope limits, and rate limiting. A publishable key cannot modify workflows, access admin endpoints, or perform actions outside its configured scope.