Auth Platform API

Self-hosted authentication microservice with OAuth 2.0 Authorization Code Flow (PKCE), email OTP verification, RS256 JWT tokens, and multi-tenant application management.

Quick Start

Get up and running in 3 steps:

Admin Dashboard: __AUTH_SERVER__/dashboard/

<script src="auth-sdk.js"></script>
<script>
  const auth = new AuthClient({
    AUTH_SERVER: '__AUTH_SERVER__',
    CLIENT_ID: 'your-client-id',
    REDIRECT_URI: window.location.origin
  });
  await auth.handleCallback();
  if (auth.isAuthenticated()) {
    console.log('Logged in as', auth.getUser().email);
    auth.startAutoRefresh();
  } else {
    auth.login(); // Redirects to hosted login
  }
</script>

Download SDK

Our JavaScript SDK handles all OAuth 2.0 + PKCE complexity for you. Just download, configure, and integrate.

Integration Guide

1. Basic Setup

Configure the SDK using environment variables — never hardcode secrets or URLs in source code.

// Read from your environment / .env file
const auth = new AuthClient({
  AUTH_SERVER:  '__AUTH_SERVER__',          // or process.env.NEXT_PUBLIC_AUTH_SERVER
  CLIENT_ID:   'app_xxxxxxxxxxxx',          // from Admin Console
  REDIRECT_URI: window.location.origin,     // must match Admin Console
});

2. Handle Authentication

// On page load — check for OAuth callback
await auth.handleCallback();

if (auth.isAuthenticated()) {
  const user = auth.getUser();
  showDashboard(user);
  auth.startAutoRefresh();  // token refresh + SSE revocation stream
} else {
  showLoginButton();
}

3. Listen for Auth Changes

Get notified in real-time when the session state changes — including admin force-logouts.

auth.onAuthChange((isLoggedIn, reason) => {
  if (!isLoggedIn) {
    if (reason === 'revoked_by_admin') {
      showBanner('Your session was ended by an administrator');
    } else if (reason === 'session_expired') {
      showBanner('Session expired — please log in again');
    }
    redirectToLogin();
  }
});

4. Making Authenticated Requests

async function fetchUserData() {
  const token = auth.getAccessToken();
 
  const response = await fetch('https://your-api.com/user/profile', {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });
 
  return response.json();
}

5. Logout

document.getElementById('logoutBtn').onclick = () => {
  auth.logout();
  window.location.href = '/';
};

Environment Setup

The SDK reads its configuration from a config object — use your framework's environment variables to supply the values. Never commit real credentials to source control.

Next.js

# .env.local
NEXT_PUBLIC_AUTH_SERVER=__AUTH_SERVER__
NEXT_PUBLIC_CLIENT_ID=app_xxxxxxxxxxxx
NEXT_PUBLIC_REDIRECT_URI=http://localhost:3000/callback

// lib/config.js
export const AUTH_CONFIG = {
  AUTH_SERVER:  process.env.NEXT_PUBLIC_AUTH_SERVER,
  CLIENT_ID:   process.env.NEXT_PUBLIC_CLIENT_ID,
  REDIRECT_URI: process.env.NEXT_PUBLIC_REDIRECT_URI,
};

Vite (Vue / React / Svelte)

# .env
VITE_AUTH_SERVER=__AUTH_SERVER__
VITE_CLIENT_ID=app_xxxxxxxxxxxx
VITE_REDIRECT_URI=http://localhost:5173/callback

const auth = new AuthClient({
  AUTH_SERVER:  import.meta.env.VITE_AUTH_SERVER,
  CLIENT_ID:   import.meta.env.VITE_CLIENT_ID,
  REDIRECT_URI: import.meta.env.VITE_REDIRECT_URI,
});

Create React App

# .env
REACT_APP_AUTH_SERVER=__AUTH_SERVER__
REACT_APP_CLIENT_ID=app_xxxxxxxxxxxx
REACT_APP_REDIRECT_URI=http://localhost:3000/callback

const auth = new AuthClient({
  AUTH_SERVER:  process.env.REACT_APP_AUTH_SERVER,
  CLIENT_ID:   process.env.REACT_APP_CLIENT_ID,
  REDIRECT_URI: process.env.REACT_APP_REDIRECT_URI,
});

Plain HTML / Vanilla JS

Since plain HTML has no build step, pass values directly or use <meta> tags:

<script src="auth-sdk.js"></script>
<script>
  const auth = new AuthClient({
    AUTH_SERVER:  '__AUTH_SERVER__',
    CLIENT_ID:   'app_xxxxxxxxxxxx',
    REDIRECT_URI: window.location.origin,
  });
</script>

SDK Reference

The SDK uses true private fields (#) — internal state like tokens and streams are completely inaccessible from outside the class.

const auth = new AuthClient({
  AUTH_SERVER:  process.env.NEXT_PUBLIC_AUTH_SERVER,
  CLIENT_ID:   process.env.NEXT_PUBLIC_CLIENT_ID,
  REDIRECT_URI: process.env.NEXT_PUBLIC_REDIRECT_URI,
});

auth.login();

auth.logout();  // voluntary logout (reason = null)

if (auth.isAuthenticated()) {
  console.log('User is logged in');
}

const user = auth.getUser();
// { email, user_id, app_id, issuer, expires_at, issued_at }

fetch('/api/data', {
  headers: { 'Authorization': `Bearer ${auth.getAccessToken()}` }
});

const handled = await auth.handleCallback();

auth.onAuthChange((isLoggedIn, reason) => {
  // reason: 'revoked_by_admin' | 'session_expired' | null
  if (!isLoggedIn && reason === 'revoked_by_admin') {
    alert('Admin ended your session');
  }
});

if (auth.isAuthenticated()) {
  auth.startAutoRefresh();
}

const ok = await auth.refreshAccessToken();

const payload = await auth.verifyToken();

console.log(`Token expires in ${auth.getTimeUntilExpiry()}s`);

OAuth Endpoints

{
  "grant_type": "authorization_code",
  "code": "auth_code_here",
  "client_id": "your_client_id",
  "redirect_uri": "https://your-app.com/callback",
  "code_verifier": "pkce_verifier"
}

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "refresh_token_here"
}

Auth Endpoints

{
  "email": "user@example.com",
  "app_id": "app_xxxxxxxxxxxx"
}

{
  "email": "user@example.com",
  "otp": "123456",
  "app_id": "app_xxxxxxxxxxxx"
}

{
  "access_token": "eyJhbGc...",
  "refresh_token": "refresh_token_here"
}

Token Management

{
  "refresh_token": "your_refresh_token"
}

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 900
}

{
  "token": "eyJhbGc..."
}

Admin Endpoints

Admin endpoints require authentication with admin credentials.

{
  "app_name": "My App",
  "redirect_uris": ["https://myapp.com/callback"],
  "session_duration": 900,
  "refresh_token_duration": 604800
}

Code Examples

React / Next.js

// .env.local
// NEXT_PUBLIC_AUTH_SERVER=__AUTH_SERVER__
// NEXT_PUBLIC_CLIENT_ID=app_xxxxxxxxxxxx
// NEXT_PUBLIC_REDIRECT_URI=http://localhost:3000/callback

import AuthClient from './auth-sdk';
import { AUTH_CONFIG } from './config';
import { useEffect, useState } from 'react';

function App() {
  const [user, setUser] = useState(null);
  const [logoutReason, setLogoutReason] = useState(null);
  const [auth] = useState(() => new AuthClient(AUTH_CONFIG));

  useEffect(() => {
    async function init() {
      await auth.handleCallback();

      auth.onAuthChange((loggedIn, reason) => {
        if (loggedIn) {
          setUser(auth.getUser());
          setLogoutReason(null);
        } else {
          setUser(null);
          setLogoutReason(reason);
        }
      });

      if (auth.isAuthenticated()) {
        setUser(auth.getUser());
        auth.startAutoRefresh();
      }
    }
    init();
  }, []);

  if (logoutReason === 'revoked_by_admin') {
    return <div className="banner">Admin ended your session</div>;
  }
  if (!user) {
    return <button onClick={() => auth.login()}>Login</button>;
  }
  return (
    <div>
      <h1>Welcome, {user.email}</h1>
      <button onClick={() => auth.logout()}>Logout</button>
    </div>
  );
}

Vue.js (Vite)

// .env
// VITE_AUTH_SERVER=__AUTH_SERVER__
// VITE_CLIENT_ID=app_xxxxxxxxxxxx
// VITE_REDIRECT_URI=http://localhost:5173/callback

import AuthClient from './auth-sdk';

export default {
  data() {
    return {
      auth: new AuthClient({
        AUTH_SERVER:  import.meta.env.VITE_AUTH_SERVER,
        CLIENT_ID:   import.meta.env.VITE_CLIENT_ID,
        REDIRECT_URI: import.meta.env.VITE_REDIRECT_URI,
      }),
      user: null,
      logoutReason: null
    };
  },
  async mounted() {
    this.auth.onAuthChange((loggedIn, reason) => {
      this.user = loggedIn ? this.auth.getUser() : null;
      this.logoutReason = reason;
    });
    await this.auth.handleCallback();
    if (this.auth.isAuthenticated()) {
      this.user = this.auth.getUser();
      this.auth.startAutoRefresh();
    }
  },
  methods: {
    login()  { this.auth.login(); },
    logout() { this.auth.logout(); }
  }
};

Protected API Route (Express)

const jwt = require('jsonwebtoken');
const fs = require('fs');
const publicKey = fs.readFileSync('public_key.pem');
function authenticateToken(req, res, next) {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1];
  if (!token) return res.sendStatus(401);
  jwt.verify(token, publicKey, { algorithms: ['RS256'] }, (err, user) => {
    if (err) return res.sendStatus(403);
    req.user = user;
    next();
  });
}
app.get('/api/protected', authenticateToken, (req, res) => {
  res.json({ message: 'Protected data', user: req.user });
});

Architecture & Flow Diagrams

Interactive sequence diagrams for all authentication flows — OAuth 2.0, OTP, WebAuthn, token refresh, multi-tenant isolation, and more.