DevAuthKit Complete Documentation

const express = require("express");
const devAuthKit = require("devauthkit");

const app = express();

// Initialize DevAuthKit (Zero-config dev mode prints OTP to console)
devAuthKit(app, {
  jwtSecret: process.env.JWT_SECRET || "your-secret-key",
  sessionSecret: process.env.SESSION_SECRET || "your-session-key",
  corsOrigin: ["http://localhost:3000", "http://localhost:5173"],
  devMode: true
});

// Protect routes with triple-strategy requireAuth middleware
app.get("/api/dashboard", devAuthKit.requireAuth, (req, res) => {
  res.json({ message: "Authenticated", user: req.user });
});

app.listen(3000, () => console.log("DevAuthKit server ready on http://localhost:3000"));

import { Hono } from "hono";
import { createHonoAuth, CloudflareD1RefreshTokenStore } from "devauthkit/hono";

const app = new Hono();

export default {
  async fetch(request, env, ctx) {
    const auth = createHonoAuth({
      jwtSecret: env.JWT_SECRET,
      d1: env.DB,
      refreshTokenStore: new CloudflareD1RefreshTokenStore(env.DB)
    });

    app.route("/auth", auth.routes);

    app.get("/api/user", auth.requireAuth, (c) => {
      return c.json({ user: c.get("user") });
    });

    return app.fetch(request, env, ctx);
  }
};

import React from "react";
import { AuthProvider, useAuth } from "devauthkit/react";

function UserProfile() {
  const { user, isAuthenticated, sendOTP, verifyOTP, logout } = useAuth();

  if (!isAuthenticated) {
    return <button onClick={() => sendOTP("user@dev.io")}>Login with OTP</button>;
  }

  return (
    <div>
      <h2>Account: {user.email}</h2>
      <button onClick={logout}>Sign Out</button>
    </div>
  );
}

export default function App() {
  return (
    <AuthProvider>
      <UserProfile />
    </AuthProvider>
  );
}

const express = require("express");
const devAuthKit = require("devauthkit");
const { MemorySsoStore } = require("devauthkit/sso");

const app = express();
devAuthKit(app, {
  jwtSecret: process.env.JWT_SECRET,
  sso: true, // ✨ Enables SAML 2.0 / OIDC SSO & domain routing
  ssoStore: new MemorySsoStore(), // Or CloudflareD1SsoStore for Workers
  spEntityId: "https://api.yourdomain.com/auth/sso/sp",
  spAcsUrl: "https://api.yourdomain.com/auth/sso/saml/acs"
});

// Admin endpoint to register Okta, Azure AD, or Google Workspace connection
const res = await fetch("https://api.yourdomain.com/auth/sso/connections", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer " + adminJwt },
  body: JSON.stringify({
    name: "Acme Corp Okta",
    type: "saml",
    entityId: "http://www.okta.com/exk123456789",
    ssoUrl: "https://acme.okta.com/app/acmeprod_app/exk123456789/sso/saml",
    certificate: "-----BEGIN CERTIFICATE-----\nMIIDpDCCAoygAwIBAgIGAX...\n-----END CERTIFICATE-----",
    allowedDomains: ["acme.com"],
    organizationId: "org_acme_corp"
  })
});

const { connection } = await res.json();
// SP Metadata XML is now live at: /auth/sso/saml/${connection.id}/metadata.xml
// ACS Endpoint is now live at: /auth/sso/saml/${connection.id}/acs

import { createDevAuthClient } from "devauthkit/client";

const devauth = createDevAuthClient({ baseUrl: "https://api.yourdomain.com" });

async function handleLogin(email) {
  // Automatically detects if email domain belongs to an enterprise SSO connection
  const sso = await devauth.resolveSso({ email });
  
  if (sso.isEnterprise) {
    // Redirects browser to Okta / Azure AD with signed Deflated SAML AuthnRequest
    devauth.loginWithSso(sso.connection.id, { redirectUrl: "/dashboard" });
  } else {
    // Fall back to Passwordless OTP, Magic Link, or Biometric Passkey
    await devauth.sendOtp({ email });
  }
}

const devAuthKit = require("devauthkit");
const { MemorySsoStore } = require("devauthkit/sso");

devAuthKit(app, {
  jwtSecret: process.env.JWT_SECRET,
  scim: true, // ✨ Mounts /scim/v2 endpoints with application/scim+json support
  ssoStore: new MemorySsoStore()
});

// Create a SCIM directory for an enterprise organization
const res = await fetch("https://api.yourdomain.com/auth/scim/directories", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer " + adminJwt },
  body: JSON.stringify({
    name: "Acme Corp Okta SCIM",
    organizationId: "org_acme_corp"
  })
});

const { directory, token } = await res.json();
// Give these credentials to the Enterprise IT Administrator:
// SCIM 2.0 Base URL: https://api.yourdomain.com/scim/v2
// SCIM Bearer Token: scim_live_... (only shown once)

// Okta / Azure AD sends RFC 7644 PATCH request when employee departs:
// PATCH /scim/v2/Users/usr_123
// Authorization: Bearer scim_live_...
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "active", "value": false }
  ]
}

// DevAuthKit executes the Instant Deprovisioning Cascade:
// 1. Updates user status: active = false
// 2. Purges user from organization workspace membership
// 3. Revokes ALL active refresh tokens across all mobile/desktop devices
// 4. Dispatches cryptographically signed webhook: user.deprovisioned

const devAuthKit = require("devauthkit");

devAuthKit(app, {
  jwtSecret: process.env.JWT_SECRET,
  webhooks: true // ✨ Enables /auth/webhooks management & auto-event dispatch
});

const { createWebhookHandler } = require("devauthkit/webhooks");

app.post("/api/webhooks/devauth", express.raw({ type: "application/json" }), createWebhookHandler({
  secret: process.env.DEVAUTH_WEBHOOK_SECRET, // "whsec_..."
  toleranceSeconds: 300,
  onEvent: async (event) => {
    switch (event.event) {
      case "org.created":
        await provisionTenantResources(event.data.organization);
        break;
      case "user.authenticated":
        await syncUserAnalytics(event.data.userId);
        break;
    }
  }
}));

const devAuthKit = require("devauthkit");

devAuthKit(app, {
  jwtSecret: process.env.JWT_SECRET,
  organizations: true // ✨ Enables /auth/orgs endpoints & workspace engine
});

const { requireOrg, requireOrgRole, requireOrgPermission } = devAuthKit;

// Context-scoped endpoint (resolves org from token org_id or x-organization-id header)
app.get("/api/projects", requireOrg, (req, res) => {
  res.json({ workspace: req.org.name, myRole: req.orgMember.role });
});

// Granular role check (owner or admin)
app.get("/api/billing", requireOrgRole(["owner", "admin"]), (req, res) => {
  res.json({ invoices: [] });
});

import { useOrg } from "devauthkit/react";

function WorkspaceSelector() {
  const { activeOrg, organizations, switchOrg, createOrg } = useOrg();

  return (
    <select value={activeOrg?.id} onChange={(e) => switchOrg(e.target.value)}>
      {organizations.map((org) => (
        <option key={org.id} value={org.id}>
          {org.name} ({org.role})
        </option>
      ))}
    </select>
  );
}

// Server configuration
devAuthKit(app, {
  dpop: true, // Activates RFC 9449 binding & replay protection store
  jwtSecret: process.env.JWT_SECRET
});

// Strict DPoP enforcement on sensitive routes
app.post("/api/transfer", devAuthKit.requireDPoP, (req, res) => {
  res.json({ success: true, dpopThumbprint: req.dpop.jkt });
});

// Client SDK initialization
const auth = new DevAuthClient({
  apiUrl: "http://localhost:3000",
  dpop: true // Transparent client-side P-256 signing
});

devAuthKit(app, {
  passkeys: {
    rpName: "DevAuthKit App",
    rpID: "myapp.com",
    origins: ["https://myapp.com"]
  },
  passkeyStore: myDurablePasskeyStore,
  passkeyChallengeStore: myAtomicChallengeStore
});

// 1. Client requests OTP
POST /auth/login
{ "email": "user@example.com" }

// Response:
{ "success": true, "message": "OTP sent", "cooldownSeconds": 60 }

// 2. Client verifies OTP
POST /auth/verify-otp
{ "email": "user@example.com", "otp": "492810" }

// Response:
{ "success": true, "token": "eyJhbGci...", "user": { "id": "...", "email": "..." } }

devAuthKit(app, {
  magicLink: true,
  magicLinkExpiryMinutes: 15,
  magicLinkSuccessURL: "http://localhost:3000/dashboard"
});

// Automatically handles verification at:
// GET /auth/verify-magic?token=...&email=...

devAuthKit(app, {
  refreshTokens: {
    accessTokenExpiresIn: "15m",
    refreshTokenExpiresInDays: 30
  },
  jwtSecret: process.env.JWT_SECRET,
  sessionSecret: process.env.SESSION_SECRET
});

// Endpoints automatically mounted:
// POST /auth/refresh            - Rotates cookie and issues new access token
// POST /auth/sessions/revoke    - Revokes current device token family
// POST /auth/sessions/revoke-all- Revokes all sessions across all devices

devAuthKit(app, {
  rateLimit: {
    requestOtp: { perEmailMax: 5, perIpMax: 30 },
    verifyOtp: { perEmailMax: 10, perIpMax: 40 }
  }
});

const { requireAuth, requireRole } = devAuthKit;

// Restrict endpoint to admin users only
app.get("/api/admin/metrics", requireAuth, requireRole(["admin", "superadmin"]), (req, res) => {
  res.json({ adminData: true, user: req.user });
});

devAuthKit(app, {
  google: {
    clientId: process.env.GOOGLE_CLIENT_ID,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    callbackURL: "http://localhost:3000/auth/google/callback",
    successRedirectURL: "http://localhost:3000/dashboard"
  },
  github: {
    clientId: process.env.GITHUB_CLIENT_ID,
    clientSecret: process.env.GITHUB_CLIENT_SECRET,
    callbackURL: "http://localhost:3000/auth/github/callback",
    successRedirectURL: "http://localhost:3000/dashboard"
  }
});

import { Hono } from "hono";
import { createHonoAuth, CloudflareD1RefreshTokenStore } from "devauthkit/hono";

const app = new Hono();

export default {
  async fetch(request, env, ctx) {
    const auth = createHonoAuth({
      jwtSecret: env.JWT_SECRET,
      d1: env.DB,
      refreshTokenStore: new CloudflareD1RefreshTokenStore(env.DB)
    });

    app.route("/auth", auth.routes);
    return app.fetch(request, env, ctx);
  }
};

const { PrismaClient } = require("@prisma/client");
const prismaAdapter = require("devauthkit/adapters/prisma");

const prisma = new PrismaClient();

devAuthKit(app, {
  userAdapter: prismaAdapter(prisma),
  mapUserPayload: (user) => ({ role: user.role, plan: user.plan })
});

const drizzleAdapter = require("devauthkit/adapters/drizzle");
const { users } = require("./schema");

devAuthKit(app, {
  userAdapter: drizzleAdapter(db, users)
});

const mongooseAdapter = require("devauthkit/adapters/mongoose");
const User = require("./models/User");

devAuthKit(app, {
  userAdapter: mongooseAdapter(User)
});

const { createClient } = require("redis");
const redis = createClient();

devAuthKit(app, {
  otpStore: new devAuthKit.RedisOtpStore(redis),
  rateLimitStore: new devAuthKit.RedisRateLimitStore(redis)
});

import { AuthProvider, useAuth } from "devauthkit/react";

function Dashboard() {
  const { user, isAuthenticated, isLoading, sendOTP, verifyOTP, logout } = useAuth();

  if (isLoading) return <div>Loading...</div>;
  if (!isAuthenticated) return <button onClick={() => sendOTP("user@dev.io")}>Login</button>;

  return (
    <div>
      <h1>Welcome, {user.email}</h1>
      <button onClick={logout}>Sign Out</button>
    </div>
  );
}

import { DevAuthClient } from "devauthkit/client";

const auth = new DevAuthClient({
  apiUrl: "http://localhost:3000",
  dpop: true // Enables hardware-bound token protection
});

// Send and verify OTP
await auth.sendOTP("alex@dev.io");
await auth.verifyOTP("alex@dev.io", "123456");

// Automatically attaches DPoP signature + Bearer header
const res = await auth.fetch("/api/dashboard");
const data = await res.json();

SESSION_SECRET=super_secret_session_key_12345
JWT_SECRET=super_secret_jwt_key_12345

# Modern Delivery via Resend (Recommended)
RESEND_API_KEY=re_123456789
FROM_EMAIL=auth@yourdomain.com

# Standard SMTP Alternative
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password

# Social OAuth Credentials
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret