Skip to content
Docs

Start typing to search the documentation.

Node.js / TypeScript SDK

On this page

@selfxyz/enterprise-sdk is the official Node/TS client for Self Enterprise. It wraps session creation, retrieval, and webhook signature verification with typed payloads.

Install

npm install @selfxyz/enterprise-sdk

Node 20+. ESM-only.

Initialize

import { SelfClient } from '@selfxyz/enterprise-sdk';

const self = new SelfClient({
  apiKey: process.env.SELF_API_KEY!, // sk_test_... or sk_live_...
});

apiKey is the only option, and the key is bound to one environment (test or live).

Sessions

Create

Get the flowId by deploying a configuration in the dashboard, it’s shown on the workspace’s Test and Live tabs. See Configure a workspace.

const session = await self.sessions.create({
  flowId: '9c0b4f1c-1d6c-4f1b-a8c4-9f0fa0a8d9e2',
  externalUuid: 'user-42', // your stable id for the user (any string up to 256 chars)
  // optional:
  expiresInSeconds: 3600,
  metadata: { campaign: 'winter-2026' },
  successUrl: 'https://app.example.com/verified', // must be http(s)
  failureUrl: 'https://app.example.com/failed', // must be http(s)
});

session.verificationUrl; // give to the user
session.id; // store on your side
session.expiresAt; // ISO-8601

Returns Session. The essentials: id is what you store and match against webhook verification_id, verificationUrl is what you hand to the user, and flowVersionId pins the flow version so a later deploy doesn’t disturb in-flight sessions. The full field table is in the SDK API reference.

Get

const detail = await self.sessions.get('7f3b2a1e-9c4d-4b2a-8e1f-2c6d5a4b3c2d'); // the session id

detail.status; // 'pending' | 'valid' | 'invalid' | 'error' | 'expired'
detail.proofAttributes; // enforced predicate config, e.g. { minimumAge: 18, ofac: true }
detail.storage.state; // 'pending' | 'committed' | 'failed' | 'skipped'

Returns SessionDetail; the full field table is in the SDK API reference. The id must be a UUID: anything else throws SelfValidationError without making a request.

Types

The SDK exports the canonical Zod schemas and their inferred types:

import type {
  SelfClientOptions, // SelfClient constructor options
  CreateSessionInput, // what you pass to .create()
  Session, // what .create() returns
  SessionDetail, // what .get() returns
  WebhookEvent, // the webhook event payload type
  VerificationCompletedPayload, // the verification.completed payload
} from '@selfxyz/enterprise-sdk';

You can also import the schemas themselves for runtime validation:

import { createSessionBody, webhookEvent } from '@selfxyz/enterprise-sdk';

const parsed = createSessionBody.parse(input);

Error handling

Every non-2xx response throws SelfApiError (statusCode, code, message, details, requestId); bad arguments throw SelfValidationError before any request is sent. The SDK doesn’t retry, handle transient 429 and 5xx responses yourself. See Error handling for the catch pattern and the full code catalog.

Was this page helpful?