Installation

The @yorauth/js-sdk package supports any JavaScript or TypeScript project. It ships with full TypeScript type definitions and has no mandatory peer dependencies.

Requirements

• Node.js 18+ (or compatible server-side JavaScript runtime: Deno, Bun, Cloudflare Workers)
• TypeScript 4.7+ (optional but recommended)

For client-side browser usage, see the framework-specific SDKs: @yorauth/react-sdk (Next.js) or @yorauth/vue-sdk (Nuxt).

Security

Server-Side vs. Client-Side Authentication

What Happens If an API Key Is Exposed

If your API key appears in client-side code:

1. Any visitor to your site can extract it from the browser's developer tools or the JavaScript bundle
2. The attacker can use the key to read, modify, or delete your application's users, roles, permissions, webhooks, and audit logs
3. YorAuth cannot distinguish between legitimate server-side requests and requests using a stolen key

If You Suspect Key Exposure

1. Immediately rotate the key in the YorAuth Dashboard under API Keys
2. Review your audit logs for unauthorized activity
3. If unauthorized access to user data occurred, follow your incident response plan and applicable breach notification requirements
4. Contact security@yorauth.com

Runtime Protection

The SDK detects browser environments and throws an error if an API key is provided in client-side code. This prevents accidental credential exposure in production builds.

If you encounter this error in a legitimate server-side context (such as during SSR hydration), ensure your API key initialization only runs on the server. In Next.js, use Server Components or API routes. In Nuxt, use server middleware or server plugins.

Package Managers

npm install @yorauth/js-sdk

yarn add @yorauth/js-sdk

pnpm add @yorauth/js-sdk

Initialization

Create a single YorAuth instance and export it from a shared module. Do not create multiple instances for the same application.

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

export const yorauth = new YorAuth({
  applicationId: 'your-application-id',
  baseUrl: process.env.YORAUTH_BASE_URL!,
  apiKey: 'your-api-key',
});

Retrieve your application ID and API key from the YorAuth Dashboard. Store them in environment variables — never commit keys to source control.

# .env
YORAUTH_APPLICATION_ID=your-application-id
YORAUTH_BASE_URL=https://your-yorauth-instance.example.com
YORAUTH_API_KEY=your-api-key

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

export const yorauth = new YorAuth({
  applicationId: process.env.YORAUTH_APPLICATION_ID!,
  baseUrl: process.env.YORAUTH_BASE_URL!,
  apiKey: process.env.YORAUTH_API_KEY!,
});

Configuration Options

The YorAuth constructor accepts the following options:

Example with All Options

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

const yorauth = new YorAuth({
  applicationId: 'your-application-id',
  baseUrl: process.env.YORAUTH_BASE_URL!,
  apiKey: 'your-api-key',
  token: 'eyJhbGciOiJSUzI1NiI...',       // optional — JWT Bearer token
  refreshToken: 'refresh-token-value',     // optional — enables auto-refresh on 401
  timeout: 15000,
});

TypeScript Support

The SDK ships with full TypeScript definitions. No @types package is needed. All method parameters and return types are typed.

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

const yorauth = new YorAuth({
  applicationId: 'your-application-id',
  baseUrl: process.env.YORAUTH_BASE_URL!,
});

// Full type inference on responses
const response = await yorauth.auth.login({
  email: 'user@example.com',
  password: 'secret',
});

Framework Integration

React / Next.js

Install the React SDK (separate package):

npm install @yorauth/react-sdk @yorauth/js-sdk

// app/providers.tsx
'use client';
import { YorAuthProvider } from '@yorauth/react-sdk';
import '@yorauth/react-sdk/styles.css';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <YorAuthProvider
      applicationId="your-app-id"
      baseUrl={process.env.NEXT_PUBLIC_YORAUTH_BASE_URL!}
    >
      {children}
    </YorAuthProvider>
  );
}

// In a component
import { useAuth, useUser } from '@yorauth/react-sdk';

export function ProfileButton() {
  const { logout } = useAuth();
  const { user } = useUser('user-uuid');

  if (!user) return <a href="/login">Sign in</a>;

  return (
    <button onClick={() => logout()}>
      Sign out ({user.email})
    </button>
  );
}

Vue 3 / Nuxt

Install the Vue SDK (separate package):

npm install @yorauth/vue-sdk @yorauth/js-sdk

// plugins/yorauth.ts
import { YorAuthPlugin } from '@yorauth/vue-sdk';
import '@yorauth/vue-sdk/styles.css';

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(YorAuthPlugin, {
    applicationId: 'your-application-id',
    baseUrl: import.meta.env.VITE_YORAUTH_BASE_URL,
  });
});

<!-- In a component -->
<script setup lang="ts">
import { useAuth } from '@yorauth/vue-sdk';
const { user, isAuthenticated, logout } = useAuth();
</script>

<template>
  <button v-if="isAuthenticated" @click="logout()">Sign out</button>
  <a v-else href="/login">Sign in</a>
</template>

Next Steps

• Authentication — Register users, log in, handle MFA
• Authorization — Check permissions, manage roles