Skip to content
Docs

Start typing to search the documentation.

SDK API reference

On this page

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 {
  SelfClientOptions, // SelfClient constructor options
  CreateSessionInput, // argument to sessions.create()
  Session, // return of sessions.create()
  SessionDetail, // return of sessions.get()
  WebhookEvent, // the webhook event payload type
  WebhookHeaders, // the request headers verify() reads
  VerificationCompletedPayload, // the verification.completed payload
} from '@selfxyz/enterprise-sdk';

The Zod schemas behind those types (createSessionBody, createSessionResponse, sessionDetailResponse, verificationCompleted, 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, and the key is bound to one environment. Throws if apiKey is missing.

sessions.create(input)

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

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

CreateSessionInput

FieldTypeRequiredNotes
flowIdstring (UUID)✓The flow to verify against.
externalUuidstring✓Your stable identifier for the user, echoed back on the webhook. Any opaque string, 1-256 chars (order-42/user-1 is fine). Not an idempotency key, see the note below.
expiresInSecondsnumber✕How long the session stays openable. Integer, 60 to 86400. Default 3600.
metadataobject✕Arbitrary JSON attached to the session. Max 4 KB serialized.
successUrlstring (URL)✕Where the hosted page sends the user on success. Must be an http(s) URL; other schemes are rejected before the request is sent.
failureUrlstring (URL)✕Where the hosted page sends the user on failure. Same http(s) rule.

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. id must be a UUID: anything else throws SelfValidationError before a request is sent.

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 | nullThe enforced predicate config echoed back (minimumAge, excludedCountries, includedCountries, ofac), null until valid. Not disclosed booleans, see the event catalog.
storageobject{ state: 'pending' | 'committed' | 'failed' | 'skipped'; uri: string | null; credentialId: string | null }. Custom Config and on-chain sessions report state: 'skipped': no off-chain record is kept for them, and uri stays 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 the webhook payload 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.nullifier);
}

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 that isn’t a UUID, or an empty externalUuid), 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, missing signature headers, or a malformed signing secret. Respond 400, a bad signature won’t pass on retry.

Was this page helpful?