Server SDK

@arkyc/sdk is a typed client for the hosted API. Use your project’s secret key on the server to create and manage verification sessions.

Install and initialize

arkyc.ts

import { Arkyc } from '@arkyc/sdk'

export const arkyc = new Arkyc({
  secretKey: process.env.ARKYC_SECRET_KEY!,
  // baseUrl defaults to the hosted API; override for self-hosted.
  // workflowId: 'wf_…', // optional default workflow for every session
})

Create a session

The project is determined by the secret key. create returns the session plus a one-time clientToken for the widget.

const { session, clientToken } = await arkyc.sessions.create({
  userReference: 'user_456',     // optional: your id for the user
  metadata: { plan: 'pro' },     // optional: stored with the session
  // workflowId: 'wf_…',         // optional: overrides the client default
})

// clientToken -> hand to the widget
// session.id  -> store to reconcile webhooks

Retrieve and cancel

const current = await arkyc.sessions.retrieve(session.id)
await arkyc.sessions.cancel(session.id)

Extracted PII

The verified identity and address data a session extracts (name, date of birth, document number, address) is available only through this server SDK, on sessions.retrieve(), authenticated with your secret key. It is never sent to the browser widget or included in webhooks. It appears on session.extracted only when your project holds a granted PII entitlement (request it under a project’s Extended access in the dashboard: choose the data categories, the timing, and a justification; a platform admin approves it).

const session = await arkyc.sessions.retrieve(sessionId)

// Present only with a granted PII entitlement; null otherwise.
if (session.extracted?.identity) {
  const { full_name, date_of_birth, document_number } = session.extracted.identity
}
if (session.extracted?.address) {
  const { line1, city, postal_code, country } = session.extracted.address
}

Only the granted categories appear (identity and/or address), and with after timing the data is withheld until the session is decided. Treat it as sensitive: request the minimum you need and store it per your own data policy.

Error handling

Failed requests throw a typed ArkycApiError carrying the HTTP status, a stable error key, and (on a 422) field-level errors.

import { ArkycApiError } from '@arkyc/sdk'

try {
  await arkyc.sessions.create({ userReference, workflowId })
} catch (err) {
  if (err instanceof ArkycApiError) {
    if (err.error === 'invalid_api_key') return rotateKey()
    if (err.error === 'invalid_workflow') return useDefaultWorkflow()
    console.error(err.status, err.error, err.message)
    if (err.errors) console.error(err.errors) // { field: [messages] } on 422
  }
}

Errors with no error key are unexpected/unhandled; treat them generically by status. The full list is in Error codes.

Webhook verification

The SDK also verifies signed webhook deliveries, see Webhooks.