JavaScript / TypeScript

The @yorauth/js-sdk package is the official YorAuth SDK for JavaScript and TypeScript applications. It provides a typed, promise-based interface for authentication, authorization, and user management that maps directly to the YorAuth REST API.

The JavaScript SDK is currently in development. This documentation describes the intended API and developer experience. The package is not yet published to npm.

Server-side only. The @yorauth/js-sdk uses API keys for authentication and must only be used in server-side Node.js environments. Never include API keys in browser-bundled JavaScript. For client-side apps, use @yorauth/react-sdk or @yorauth/vue-sdk with an SSR framework.

Key Features

Full TypeScript support with bundled type definitions
Automatic access token refresh using the stored refresh token
Secure token storage abstraction (localStorage, sessionStorage, or custom)
TOTP multi-factor authentication support
Passwordless magic link authentication
RBAC role and permission management
Single and bulk permission checks with ABAC context support
Framework integration helpers for React, Next.js, and Vue

Installation

Install the package using your preferred package manager:

bash

npm install @yorauth/js-sdk

See the Installation guide for full setup instructions, configuration options, and framework-specific setup.

Quick Example

typescript

import { YorAuth } from '@yorauth/js-sdk';

const yorauth = new YorAuth({
  applicationId: 'your-application-id',
  apiKey: 'your-api-key',
});

// Register a new user
const { data: user } = await yorauth.auth.register({
  email: 'jane@example.com',
  password: 'super-secret-password',
  name: 'Jane Doe',
});

// Log in
const { data: session } = await yorauth.auth.login({
  email: 'jane@example.com',
  password: 'super-secret-password',
});

console.log(session.access_token);
console.log(session.user.id);

// Check a permission
const { allowed } = await yorauth.permissions.check(
  session.user.id,
  'posts:create',
);

console.log(allowed); // true or false

SDK Structure

The SDK is organized into namespaces that correspond to resource groups in the API:

Namespace	Description	Docs
`yorauth.auth`	Registration, login, logout, token refresh, MFA, magic links, CAPTCHA	Authentication
`yorauth.users`	Profile management, password change, data export, consent withdrawal	Authentication
`yorauth.roles`	Create, list, update, delete roles; assign/revoke to users	Authorization
`yorauth.permissions`	Single and bulk permission checks	Authorization
`yorauth.teams`	Team CRUD, member management, team role assignments	Authorization
`yorauth.sessions`	List, revoke individual or all sessions	Authentication
`yorauth.mfa`	TOTP setup/confirm/disable, backup codes, MFA status	Authentication
`yorauth.oidc`	OIDC client management, discovery, JWKS, authorize, token, device auth, client credentials	Authentication
`yorauth.passkeys`	WebAuthn/passkey authentication and credential management	Authentication
`yorauth.saml`	SAML SSO initiation and connection listing	Authentication
`yorauth.userAttributes`	User attribute management for ABAC	Authorization
`yorauth.webhooks`	Webhook configuration and delivery history
`yorauth.apiKeys`	API key management
`yorauth.auditLogs`	Audit log viewing with filters

Error Handling

All SDK methods return a promise that rejects with a YorAuthError on API errors. The error object includes a code field that maps to the YorAuth error code catalog.

typescript

import { YorAuth, YorAuthError } from '@yorauth/js-sdk';

try {
  await yorauth.auth.login({ email: 'user@example.com', password: 'wrong' });
} catch (err) {
  if (err instanceof YorAuthError) {
    console.error(err.code);    // 'AUTH_INVALID_CREDENTIALS'
    console.error(err.message); // Human-readable message
    console.error(err.status);  // HTTP status code (401)
  }
}

Next Steps

Installation — Package setup and configuration
Authentication — Login, registration, MFA, magic links
Authorization — Roles, permissions, and access checks