Skip to Content
SDKsCore

BinoAuth Core SDK

The main BinoAuth SDK for Node.js applications, providing OAuth 2.0, authentication flows, and admin operations.

Recommended for most applications. Includes all BinoAuth features including OAuth, password flows, magic links, OTP, MFA, and admin operations.

Installation

npm install binoauth

Quick Start

OAuth Configuration

import { BinoAuthOAuth } from 'binoauth';
 
const oauth = new BinoAuthOAuth({
  issuer: 'https://auth.binoauth.com',
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  scope: 'openid profile email'
}, {
  encryptionKey: 'your-32-char-encryption-key',
  storage: 'memory' // or 'localStorage', 'sessionStorage'
});

Authentication Flow

// Get login URL
const loginUrl = await oauth.getLoginUrl();
 
// Handle callback
const { code, state } = req.query;
await oauth.handleCallback(code, state);
 
// Get user info
const user = await oauth.getUserInfo();

Direct Authentication

import { BinoAuthClient } from 'binoauth';
 
const client = new BinoAuthClient({
  issuer: 'https://auth.binoauth.com',
  clientId: 'your-client-id',
  apiKey: 'your-api-key'
});
 
// Password authentication
const result = await client.password.login({
  email: 'user@example.com',
  password: 'password123'
});
 
// Magic link authentication
await client.magicLink.send('user@example.com');

OAuth 2.0 Client

Configuration

import { BinoAuthOAuth } from 'binoauth';
 
const oauth = new BinoAuthOAuth({
  issuer: 'https://auth.binoauth.com',
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  scope: 'openid profile email'
}, {
  encryptionKey: 'your-32-char-encryption-key',
  storage: 'memory'
});

OAuth Methods

// Authentication flow
const loginUrl = await oauth.getLoginUrl();
const logoutUrl = await oauth.getLogoutPageUrl();
await oauth.handleCallback(code, state);
 
// User information
const user = await oauth.getUserInfo();
const isAuthenticated = await oauth.isAuthenticated();
 
// Token management
const accessToken = await oauth.getAccessToken();
const refreshToken = await oauth.getRefreshToken();
await oauth.refreshTokens();
await oauth.revokeTokens();

Authentication Flows

Password Flow

import { BinoAuthClient } from 'binoauth';
 
const client = new BinoAuthClient({
  issuer: 'https://auth.binoauth.com',
  clientId: 'your-client-id',
  apiKey: 'your-api-key'
});
 
// Login
const result = await client.password.login({
  email: 'user@example.com',
  password: 'password123'
});
 
// Signup
const signupResult = await client.password.register({
  email: 'user@example.com',
  password: 'password123',
  name: 'John Doe'
});
// Send magic link
await client.magicLink.send('user@example.com');
 
// Verify magic link
const result = await client.magicLink.verify('magic-link-token');

OTP Flow

// Send OTP (SMS only)
await client.otp.send('+1234567890');
 
// Verify OTP
const result = await client.otp.verify({
  phone: '+1234567890',
  code: '123456'
});

Social Authentication

// Get available providers
const providers = await client.social.getProviders();
 
// Get social login URL
const loginUrl = providers.google.authUrl;
 
// Handle social callback
const result = await client.social.callback(code, state, 'google');

Admin Operations

import { BinoAuthClient } from 'binoauth';
 
const client = new BinoAuthClient({
  issuer: 'https://auth.binoauth.com',
  clientId: 'your-client-id',
  apiKey: 'your-api-key'
});
 
// User management
const users = await client.admin.getUsers();
const user = await client.admin.getUser('user-id');
 
// Client management
const clients = await client.admin.getClients();
const newClient = await client.admin.createClient({
  name: 'My App',
  redirect_uris: ['https://myapp.com/callback']
});
 
// API key management
const apiKeys = await client.admin.getApiKeys();
const newKey = await client.admin.createApiKey({
  name: 'My API Key',
  scopes: ['read:users']
});

Token Storage

import { 
  InMemoryTokenStorage, 
  LocalStorageTokenStorage, 
  SessionStorageTokenStorage 
} from 'binoauth';
 
// In-memory storage (server-side)
const memoryStorage = new InMemoryTokenStorage({
  clientId: 'your-client-id',
  encryptionKey: 'your-encryption-key'
});
 
// Browser storage (client-side)
const localStorage = new LocalStorageTokenStorage({
  clientId: 'your-client-id',
  encryptionKey: 'your-encryption-key'
});
 
const sessionStorage = new SessionStorageTokenStorage({
  clientId: 'your-client-id',
  encryptionKey: 'your-encryption-key'
});

Error Handling

import { AuthError, AuthErrorCode, getErrorMessage } from 'binoauth';
 
try {
  const result = await oauth.handleCallback(code, state);
} catch (error) {
  if (error instanceof AuthError) {
    switch (error.code) {
      case AuthErrorCode.INVALID_GRANT:
        console.log('Invalid authorization code');
        break;
      case AuthErrorCode.TOKEN_EXPIRED:
        console.log('Token expired');
        break;
      default:
        console.log(getErrorMessage(error));
        break;
    }
  }
}

TypeScript Support

The SDK is fully typed with TypeScript. Import types as needed:

import type {
  BinoAuthConfig,
  AuthConfig,
  User,
  TokenResponse,
  LoginRequest,
  SignupRequest,
  MagicLinkRequest,
  OTPRequest,
  MFAChallenge
} from 'binoauth';
Last updated on
OverviewReact