TypeScript SDK
Install the server SDK and choose the scopes required by each operation.
For Web, macOS and Windows login through the system browser, use a maintained OIDC client library and the business OAuth / OIDC guide. The default @virtneu/auth entry is the service-credential SDK for business backends using /v1. Native OIDC applications use a public client with PKCE and never embed a service credential. The separate OIDC OpenAPI is independent of the SDK's bundled /v1 contract.
SDK 0.7.0 is published on npm with a separately bundled @virtneu/auth/browser client/panel for embedded passkeys. Swift/Android adapter sources live separately in the repository; they are not part of the npm archive. This route uses your own protected backend and a DNS-verified customer RP, with no Auth service/session/flow tokens in the browser or App. Published 0.6.0 does not contain this subpath. Use the matching API/schema/configuration; package publication and compilation are separate from production activation and physical-device acceptance.
Install the server SDK in your backend project:
npm install @virtneu/authThe command installs the version tagged latest on the npm package page. 0.7.0 is published and passed 25 empty-cache registry consumer checks: all seven package files match the approved archive, with 16 backend security methods and a 41-operation HTTP contract. The new beginEmbeddedPasskeyLogin selects the embedded context of an existing operation; it does not add another HTTP operation. New capabilities still require the matching API deployment and schema; npm publication does not establish production API activation. The two readiness endpoints are documented in the contract and do not have dedicated SDK methods. Exact source, integrity and registry consumer evidence are recorded in the release record.
Published version 0.6.0 adds passkey names, device and last-use metadata and policy-eligible passkey enrollment from a primary continuation. The immutable 0.5.0 package retains its 14 security methods and 40-operation contract.
The SDK ships ESM, TypeScript declarations, and its versioned OpenAPI contract. It has no runtime dependencies and is verified on Node.js 24 and Cloudflare Workers. Configure one client per app and environment as shown in the Quickstart.
See Users for directory and access checks, and Metadata for the current fields and replacement examples. If an existing key lacks users:read or users:status, issue a new key with the required scopes and rotate the credential configured in your backend.
| SDK methods | API key scope |
|---|---|
createChallenge, verifyChallenge, getMailReadiness | auth:challenge |
registerUser | auth:register |
registerUserAndSession | auth:register, auth:login |
createSession | auth:login |
validateSession | sessions:validate |
getSessionContext (requires SDK 0.4.0 or later) | sessions:validate, users:read, metadata:read — all required |
refreshSession | sessions:refresh |
revokeSession | sessions:revoke |
resetPassword | auth:password_reset |
lookupUser, getUser, getUsers, listUsers | users:read |
checkUserAccess | users:status |
setUserDisabled | users:write |
revokeUserSessions | users:sessions:revoke |
deleteUser | users:delete |
listAuthenticationEvents | auth-events:read |
getApplicationMetadata, getUserMetadata | metadata:read |
replaceApplicationMetadata, replaceUserMetadata | metadata:write |
getMfaStatus, listPasskeys, listSocialConnections | sessions:validate |
prepareMfaEnrollment, confirmMfaEnrollment, verifyMfa | auth:login |
disableMfa, regenerateMfaRecoveryCodes | auth:login, sessions:validate |
beginPasskeyRegistration, finishPasskeyRegistration, deletePasskey | auth:login, sessions:validate |
beginPasskeyLogin, beginEmbeddedPasskeyLogin, finishPasskeyLogin | auth:login |
renamePasskey (0.6.0) | auth:login, sessions:validate; recent complete user session |
unlinkSocialConnection | auth:login, sessions:validate |
Methods return { data, request_id }. The default request timeout is 15 seconds, and retries are handled by your backend. See Troubleshooting for timeout and idempotency guidance.
getSessionContext requires SDK 0.4.0 or later. Its HTTP route is POST /v1/sessions/context; deploy the matching API before updating consumers. Existing 0.3.0 clients remain compatible but do not provide this method. See Browser session renewal for the response shape and a reusable long-session policy.
The installed SDK's matching contract is bundled at @virtneu/auth/openapi.json; 0.7.0 and immutable 0.6.0 contain 41 operations, while immutable 0.5.0 contains 40. The website download follows the website's separately deployed version. Use the installed package's contract when checking its exact SDK version. The npm package includes its README, server and browser declarations/ESM bundles, and matching contract, with no runtime dependencies. The immutable 0.4.0 and 0.3.0 packages retain their earlier 26- and 23-operation contracts.
MFA, passkeys and social connections
Registration and login return Session | AuthenticationContinuation, introduced in 0.5.0 and extended in 0.6.0 with the passkey paths below. An HTTP 202 continuation contains authentication_token, next_step and methods, without a session token. Narrow with 'authentication_required' in data, keep the continuation in the protected sign-in attempt, complete the offered enrollment or verification method, then check the returned result before setting a session cookie. See Authentication and sessions.
Configure MFA, passkeys and the passkey UV policy in Studio for each App/environment. getMfaStatus, enrollment, verification, disabling and recovery-code regeneration use the user's real authentication attempt or recent complete session. Factor mutations revoke older sessions and require fresh authentication; do not automatically retry an uncertain result.
Without an embedded context, passkey ceremonies run on the platform-hosted authentication domain. A customer's webpage cannot perform a ceremony for that RP. With the matching 0.7.0 SDK and verified embedded configuration, the backend's beginEmbeddedPasskeyLogin({client_context}, options?) or registration context uses the customer RP instead. Context and allowed origins are server-owned. Existing hosted keys must be enrolled again for the new RP. The authenticator owns the private key; a browser's cross-device QR is separate from TOTP enrollment. See embedded setup and the device explanation.
With matching 0.7.0 SDK/API/schema, listPasskeys returns id, name, device_type, created_at, nullable last_used_at, backed_up, rp_id and binding_kind (hosted or embedded). renamePasskey({session_token,passkey_id,name}) updates an owned credential's display label using a recent complete session. Names are trimmed, contain 1–80 characters and cannot contain control characters. A rename preserves sessions; credential creation and removal invalidate older sessions.
Only a continuation with next_step: "enroll" that explicitly offers passkey may authorize first-time passkey setup with its primary authentication_token; the account must have no passkey or verified TOTP. Registration options accept exactly one of this token or a recent complete session_token, plus an optional name. next_step: "mfa", methods: ["passkey"] requires restarting authentication with an existing passkey, not enrolling a new passkey or TOTP from the password-only attempt. After verify, reauthentication_required: true means ordinary credential addition requires sign-in again. reauthentication_required: false with authentication means first-time setup completed the current policy and returned a full session. Check this branch before setting a session cookie. An existing factor cannot be replaced or skipped by primary enrollment.
To open security settings from an already signed-in application, use the separate OIDC account-security request, not a service credential in the browser. It uses the current OIDC access token, fresh callback/state/nonce/PKCE and same-user reauthentication, then returns a new code to replace the application's connection. No /v1 session-token bridge is provided.
Google, GitHub and Apple sign-in and explicit linking also use hosted OIDC. The SDK adds listSocialConnections and unlinkSocialConnection, not a provider-token login shortcut. Configure each provider's credentials and callback in Studio. The npm README contains the complete method contract and examples.
Only the current X-Virtneu-Auth-* context headers and metadata field names are supported. The SDK sends these headers automatically. Legacy header names cannot supply the authorization context, and the old user-metadata payload field names are rejected.