API Reference

Condensed reference for the TryMellon JavaScript SDK public API.

TryMellon

Main entry point. Create a client with your app configuration. Prefer TryMellon.create() so invalid config returns a Result instead of throwing.

import { TryMellon } from '@trymellon/js';

const clientResult = TryMellon.create({
  appId: 'YOUR_APP_ID',
  publishableKey: 'cli_xxxx',
});
if (!clientResult.ok) throw clientResult.error;
const client = clientResult.value;

TryMellonConfig

Static methods

Deprecated: new TryMellon(config) — throws on invalid config instead of returning a Result. Use TryMellon.create(config) instead.

signUp(options?)

Registers a new passkey for the user. Returns a Result with sessionToken on success.

const result = await client.signUp({ externalUserId: 'user_123' });

RegisterOptions

RegisterResult

signIn(options?)

Authenticates the user with an existing passkey. Returns a Result with sessionToken on success.

const result = await client.signIn({ externalUserId: 'user_123' });

AuthenticateOptions

AuthenticateResult

session.verify(sessionToken)

Client-side check: validates a session token against the API. Returns a Result indicating whether the session is valid. You must pass the token; the SDK does not read cookies. See Session validation.

const result = await client.session.verify(sessionToken);
if (result.ok && result.value.valid) {
  // Session is valid
}

SessionValidateResponse

Fields are camelCase in the SDK response. The raw REST API returns snake_case fields nested in a data envelope — see Backend validation for the raw HTTP contract.

session.verifyOffline(sessionToken)

Offline JWT validation — verifies the RS256 signature and claims locally against the JWKS exposed at /.well-known/jwks.json. No network round-trip per call; the JWKS is cached for 1 hour. Available since SDK v3.4.0. See Backend validation for when to prefer offline vs remote.

const result = await client.session.verifyOffline(sessionToken);
if (result.ok) {
  console.log(result.value.userId, result.value.customClaims);
}

Runs on WebCrypto. RS256 is locked — any other algorithm is rejected. Clock skew tolerance is ±30 s. The namespace https://trymellon.dev/claims is flattened into the top-level customClaims field.

SessionClaims

capabilities()

Returns the client’s WebAuthn environment status. Use to decide whether to offer passkey or email fallback.

const status = await client.capabilities();

ClientStatus

on(event, callback)

Subscribe to SDK events (e.g. for loading spinners or analytics). Returns an unsubscribe function.

const unsub = client.on('success', (payload) => {
  console.log(payload.operation, payload.token);
});
// later: unsub();

Events: start, success, error, cancelled. See Events & Error handling.

otp

Email OTP fallback when WebAuthn is not available.

See Fallback by email.

identity

Link and unlink secondary identifiers (email, wallet) on a signed-in user. Available only when preset: 'web3' — on a 'saas' client the namespace is absent at compile time. userId is implicit: resolved from the current session. Calling any method without an active session returns INVALID_ARGUMENT.

See Identity linking.

siwe

Sign-In with Ethereum (EIP-4361). Available only when preset: 'web3'. prepareMessage is a pure helper — zero dependencies, safe to call outside a session. verifyAndSignIn issues a session token after signature verification.

See SIWE login.

crossDevice

Cross-device authentication (QR login). Desktop initiates, mobile approves.

See Cross-device auth.

enroll(options)

Enrolls a device or entity using a single-use ticket issued by your backend. Used for the Entity Enrollment (Keys & Padlock) flow.

const result = await client.enroll({ ticketId: 'ticket_xxx' });
if (result.ok) {
  console.log('Session token:', result.value.sessionToken);
  console.log('Credential:', result.value.credentialId);
}

EnrollmentResult

Returns Result<EnrollmentResult, TryMellonError>. See Entity Enrollment.

getContextHash()

Returns the context hash bound to the current browser session. This hash ties an enrollment ticket to a specific client context — pass it when issuing a ticket from your backend so replay on a different origin fails.

const contextHash = client.getContextHash();
// Send to your backend when requesting a ticket

Returns string (64-char hex, SHA-256). Persisted in sessionStorage for the duration of the session.

bridge

Bridge flows for QR-based enrollment and authentication from a second device (e.g. mobile scanning a desktop QR).

See Cross-device auth and Entity Enrollment.

passkey.recover(options)

Recovers an account using an email OTP and creates a new passkey. Requires server-side initiation first.

const result = await client.passkey.recover({
  externalUserId: 'user_123',
  otp: '632145',
});

Returns Result<RecoverAccountResult, TryMellonError>. See Account Recovery.

Wire format note: The SDK sends external_id (not external_user_id) to the recovery endpoint — a historical field preserved for backend compatibility. Pass externalUserId in your SDK call as usual; the conversion is automatic.

version()

Returns the SDK version string.

console.log(client.version()); // e.g. '3.0.0'

SANDBOX_SESSION_TOKEN

Exported constant — the fixed token returned in sandbox mode. Use it in your backend to identify sandbox sessions during development.

import { SANDBOX_SESSION_TOKEN } from '@trymellon/js';

Utility exports

Helper functions exported from @trymellon/js:

@trymellon/js/platform · hosted onboarding

Sub-path for platforms that onboard their own maintainers onto TryMellon. Stateless — no publishable key. Full guide → Hosted onboarding.

import { createPlatform } from '@trymellon/js/platform';

const platform = createPlatform({ apiBaseUrl: 'https://api.trymellonauth.com' });

createPlatform(config?)

Returns TryMellonPlatform — 3 methods.

createSignupLink(options)

const link = await platform.createSignupLink({
  returnUrl: 'https://acme.com/onboarded',
  userRole: 'maintainer',
  refreshUrl: 'https://acme.com/signup-expired', // optional
  prefill: { companyName: 'ACME', email: 'f@acme.com' }, // UX only
});
// link.ok = true ⇒ link.value = { sessionId, hostedUrl, expiresInSeconds }

Client-side guards (fail-fast, zero HTTP): returnUrl must be https, refreshUrl (if present) must also be https.

getSignupStatus(sessionId)

Returns { status: 'pending_data' | 'pending_passkey' | 'completed' | 'expired' | 'failed', hostedUrl?, expiresInSeconds? }.

awaitSignupCompletion(sessionId, options?)

const controller = new AbortController();
const done = await platform.awaitSignupCompletion(sessionId, {
  signal: controller.signal,
  intervalMs: 2_000, // default
  maxAttempts: 60,   // default (~2 min)
});

Polls getSignupStatus until terminal. Rejects ABORT_ERROR on signal.abort(), TIMEOUT on exhaustion, SESSION_EXPIRED/SERVER_ERROR on terminal failure.

Type-level narrow: on the main TryMellon client, client.platform is typed never across every preset. Use the sub-path import — the TS compiler will reject client.platform.*.

Web Components

The SDK ships pre-built Web Components in @trymellon/js/ui. See Web Components for full documentation.

<script type="module">
  import '@trymellon/js/ui';
</script>
<trymellon-auth app-id="YOUR_APP_ID" publishable-key="cli_xxxx"></trymellon-auth>

Result type

All async methods that can fail return a Result<T, E>:

Check result.ok before accessing result.value; use !result.ok and result.error for error handling.

TryMellonError

Error codes: NOT_SUPPORTED, USER_CANCELLED, PASSKEY_NOT_FOUND, SESSION_EXPIRED, NETWORK_FAILURE, INVALID_ARGUMENT, TIMEOUT, ABORT_ERROR, CHALLENGE_MISMATCH, RATE_LIMIT_EXCEEDED, TICKET_NOT_FOUND, TICKET_EXPIRED, TICKET_ALREADY_USED, PIN_MISMATCH, PIN_LOCKED, BRIDGE_SESSION_EXPIRED, OTP_INVALID_OR_EXPIRED, ACTION_CHALLENGE_EXPIRED, ACTION_ALREADY_CLAIMED, ACTION_PAYLOAD_MISMATCH, SECRET_ROTATION_FORBIDDEN, JWT_KID_MISMATCH, INTROSPECTION_FAILED, CUSTOM_CLAIM_NOT_ALLOWED, CUSTOM_CLAIMS_TOO_LARGE, FORBIDDEN, SERVER_ERROR, UNKNOWN_ERROR. See Events & Error handling.