Skip to content
Docs

Start typing to search the documentation.

SDK API reference

The public surface of @selfxyz/enterprise-sdk you use to create sessions and verify webhooks. For a guided walkthrough, start with the SDK overview.

Exports

import {
  SelfClient,               // the API client
  SelfWebhooks,             // webhook signature verification
  SelfApiError,             // thrown on a non-2xx API response
  SelfValidationError,      // thrown on invalid input / unknown payload
  WebhookVerificationError, // thrown on a bad webhook signature
} from '@selfxyz/enterprise-sdk';

import type {
  CreateSessionInput,                  // argument to sessions.create()
  Session,                             // return of sessions.create()
  SessionDetail,                       // return of sessions.get()
  WebhookEvent,                        // discriminated union of webhook events
  VerificationCompletedPayload,        // the verification.completed payload
} from '@selfxyz/enterprise-sdk';

The Zod schemas behind those types (createSessionBody, sessionDetailResponse, webhookEvent) are also exported as values if you want runtime validation.

SelfClient

new SelfClient({ apiKey: string })

The API client. apiKey is your sk_test_… or sk_live_… key; the environment is determined by its prefix. Throws if apiKey is missing.

sessions.create(input)

sessions.create(input: CreateSessionInput): Promise<Session>

Creates a verification session against the published flow and returns a URL to send the user to.

CreateSessionInput

FieldTypeRequiredNotes
flowIdstring (UUID)✅The flow to verify against.
externalUuidstring (UUID)✅Your stable identifier for the user. Must be a UUID.
expiresInSecondsnumberNoHow long the session stays openable. Integer, 60 to 86400. Default 3600.
metadataobjectNoArbitrary JSON attached to the session. Max 4 KB serialized.
successUrlstring (URL)NoWhere the hosted page sends the user on success.
failureUrlstring (URL)NoWhere the hosted page sends the user on failure.

Session (the return)

FieldTypeNotes
idstringThe session ID. Match it against webhook verification_id.
externalUuidstringEchoes your input.
status'pending'Always pending at creation.
flowVersionIdstringThe pinned flow version.
verificationTokenstringOpaque token (verify_<env>_…).
verificationUrlstringThe URL to hand to the user.
createdAtstringISO-8601.
expiresAtstringISO-8601.
completedAtnullAlways null at creation.

Throws SelfApiError on a non-2xx response.

sessions.get(id)

sessions.get(id: string): Promise<SessionDetail>

Reads a session’s current state.

SessionDetail (the return)

FieldTypeNotes
idstringThe session ID.
status'pending' | 'valid' | 'invalid' | 'error' | 'expired'Current state.
createdAtstringISO-8601.
completedAtstring | nullISO-8601, null until terminal.
expiresAtstringISO-8601.
flowVersionIdstringThe pinned flow version.
externalUuidstringYour identifier from create.
metadataobject | nullWhat you passed to create.
predicatesConfigobject | nullThe rules this ran against.
proofAttributesobject | nullDisclosed results, null until valid.
storageobject{ state: 'pending' | 'committed' | 'failed'; uri: string | null; credentialId: string | null }.

Throws SelfApiError (for example 404 if the ID is unknown).

SelfWebhooks

SelfWebhooks.verify(payload, headers, secret)

SelfWebhooks.verify(
  payload: string | Buffer,
  headers: Record<string, string>,
  secret: string,
): WebhookEvent

Verifies a webhook signature and returns the typed, parsed event.

ParameterNotes
payloadThe raw request body (string or Buffer), not a parsed object.
headersThe request headers from the delivery (pass the full headers object; they carry the signature).
secretThe endpoint’s signing secret (whsec_…).

Throws WebhookVerificationError if the signature is invalid or the timestamp is stale, and SelfValidationError if the body doesn’t match any known event shape (usually an out-of-date SDK).

WebhookEvent is a discriminated union on type. The event delivered to your endpoints is verification.completed (VerificationCompletedPayload):

if (event.type === 'verification.completed' && event.status === 'valid') {
  // event is VerificationCompletedPayload here
  await markUserVerified(event.external_uuid, event.proof_attributes);
}

See the event catalog for the payload’s fields.

Errors

SelfApiError

Thrown when the API returns a non-2xx response.

PropertyTypeNotes
statusCodenumberHTTP status.
codestringStable machine-readable code (validation_failed, not_found, …).
messagestringHuman-readable.
detailsRecord<string, unknown> | undefinedExtra context (for example validation issues).
requestIdstring | undefinedThe X-Request-Id response header, when present. Quote it to support.

See Error handling for the code catalog.

SelfValidationError

Thrown when arguments fail schema validation before a request is sent (for example a flowId or externalUuid that isn’t a UUID), and by SelfWebhooks.verify(...) when a verified payload doesn’t match any known event shape.

PropertyTypeNotes
issuesZodIssue[]Which fields failed and why.
messagestringHuman-readable summary.

WebhookVerificationError

Thrown by SelfWebhooks.verify(...) on a bad signature, stale timestamp, or missing headers. Respond 400, a bad signature won’t pass on retry.