Client SDK (browser)

import { GhaymaAuth } from "@ghayma/sdk/client";
 
const auth = new GhaymaAuth({ appSlug: "my-auth-app" });
 
// Register a new user
const session = await auth.register({
  email: "[email protected]",
  password: "securepass123",
  name: "John Doe",
});
 
// Login
const { user } = await auth.login({
  email: "[email protected]",
  password: "securepass123",
});
 
// Get profile (auto-refreshes token if expired)
const me = await auth.getUser();
 
// Check auth state
console.log(auth.isAuthenticated()); // true
 
// Logout
await auth.logout();

const auth = new GhaymaAuth({
  appSlug: "my-auth-app",                          // Required — your Auth App slug
  baseUrl: "https://auth.ghayma.tech",          // Default
  storage: "memory",                                // "memory" (default) or "localStorage"
  autoRefresh: true,                                // Auto-refresh tokens (default: true)
});

// SPA — persist sessions across page refresh
const auth = new GhaymaAuth({
  appSlug: "my-auth-app",
  storage: "localStorage",
});

const session = await auth.register({
  email: "[email protected]",
  password: "securepass123",  // min 8, max 128 chars
  name: "John Doe",           // optional
});
 
console.log(session.user);         // { id, email, name, ... }
console.log(session.access_token); // JWT (if email verification not required)

const session = await auth.login({
  email: "[email protected]",
  password: "securepass123",
});
 
console.log(session.user);          // User profile
console.log(session.access_token);  // JWT access token
console.log(session.expires_in);    // Seconds until expiry (default 900)

await auth.logout();
// Revokes the refresh token server-side and clears local session

const tokens = await auth.refreshToken();
console.log(tokens.access_token);  // New JWT

const user = await auth.getUser();
console.log(user.id);             // "5729d517-..."
console.log(user.email);          // "[email protected]"
console.log(user.name);           // "John Doe"
console.log(user.avatar_url);     // "https://..."
console.log(user.email_verified); // true
console.log(user.provider);       // "email" | "google" | "github"

const updated = await auth.updateUser({
  name: "Jane Doe",
  avatar_url: "https://example.com/photo.jpg",
  metadata: { theme: "dark", lang: "fr" },
});

await auth.changePassword({
  current_password: "oldpass123",
  new_password: "newpass456",
});
// Every session ends, this one included: the local session is cleared and
// the user signs in again with the new password

await auth.changeEmail({
  new_email: "[email protected]",
  current_password: "currentpass123",
});
// A confirmation link is emailed to the new address.
// The user stays signed in with the current email until they click it.
// On confirm, every session ends and the user signs in with the new email.

await auth.cancelEmailChange();
// Cancels a pending email-change request. Idempotent — safe even with no pending request.

// Email accounts — password confirmation required
await auth.deleteAccount({ password: "mypassword" });
 
// OAuth accounts — no password needed
await auth.deleteAccount();

const result = await auth.login({ email, password });
 
if ("two_fa_required" in result) {
  // Enrolled user — ask for their authenticator code, then:
  const session = await auth.verify2FA({
    challenge_token: result.challenge_token,
    code: userInput, // TOTP code or a recovery code
  });
} else if ("two_fa_enrollment_required" in result) {
  // App enforces 2FA and this user isn't enrolled yet: enrolling with the
  // enroll_token completes the login
  const { otpauth_uri } = await auth.enrollTotp({ enroll_token: result.enroll_token });
  // Show otpauth_uri as a QR code, then confirm with the first code
  const res = await auth.confirmTotp({ code: userInput, enroll_token: result.enroll_token });
  // res.recovery_codes are shown this once; the session is stored
} else {
  // Plain session — signed in.
}

// 1. Start — render otpauth_uri as a QR code (or show the secret for
//    manual entry). Pass enroll_token only on the enforced-login path.
const { secret, otpauth_uri } = await auth.enrollTotp();
 
// 2. Confirm with a code from the authenticator app.
const res = await auth.confirmTotp({ code: "123456" });
 
// res.recovery_codes — 10 single-use codes, shown ONLY THIS ONCE.
// Display them and offer a download; the user stores them safely.

const { recovery_codes } = await auth.regenerateRecoveryCodes({
  password: currentPassword,
  code: currentCode, // TOTP or an unused recovery code
});
// Previous codes are all invalidated.

await auth.disable2FA({ password: currentPassword, code: currentCode });
// A localized security notice is emailed to the account address.

await auth.forgotPassword({ email: "[email protected]" });
// Always returns success (prevents email enumeration)

// Use the token from the reset email
await auth.resetPassword({
  token: "reset-token-from-email",
  password: "newpassword123",
});

const { valid, email } = await auth.verifyResetToken({ token });

// pages/reset-password.tsx — on your own domain
const token = new URLSearchParams(window.location.search).get("token")!;
 
// Strip the token from the URL so it doesn't linger in history
window.history.replaceState(null, "", window.location.pathname);
 
// Optional: pre-check and show who is resetting
const { email } = await auth.verifyResetToken({ token });
 
// Then submit the new password
await auth.resetPassword({ token, password: newPassword });

await auth.resendVerification({ email: "[email protected]" });

// Start: the user is sent to the provider. With flow: "pkce" the callback
// receives a one-time code instead of tokens, so nothing sensitive is in the URL.
await auth.signInWithOAuth("google", {
  redirectUri: "https://myapp.com/auth/callback",
  flow: "pkce",
});

// On your callback page: exchanges ?code= for a session (or reads the
// legacy #access_token= fragment) and scrubs the code from the address bar.
if (await auth.handleOAuthRedirect()) {
  const user = await auth.getUser();
}

const session = await auth.signInWithIdToken({ provider: "google", idToken, nonce });

import { generatePkce } from "@ghayma/sdk/client";
 
const { codeVerifier, codeChallenge } = await generatePkce();
const url = auth.getOAuthUrl("github", { redirectUri, codeChallenge });
// ... send the user to url, keep codeVerifier for the callback ...
const session = await auth.exchangeCodeForSession({ code, codeVerifier });

import { TwoFactorRequiredError } from "@ghayma/sdk/client";
 
try {
  await auth.handleOAuthRedirect();
} catch (err) {
  if (!(err instanceof TwoFactorRequiredError)) throw err;
  const step = err.result;
 
  if ("two_fa_required" in step) {
    const code = await askUserForCode(); // TOTP or a recovery code
    await auth.verify2FA({ challenge_token: step.challenge_token, code });
  } else {
    // Enforced policy, user not enrolled yet
    const { otpauth_uri } = await auth.enrollTotp({ enroll_token: step.enroll_token });
    const code = await askUserForCode(otpauth_uri); // show the QR code first
    await auth.confirmTotp({ code, enroll_token: step.enroll_token });
  }
}

const unsubscribe = auth.onAuthStateChange((event, session) => {
  switch (event) {
    case "SIGNED_IN":
      console.log("User signed in");
      break;
    case "SIGNED_OUT":
      console.log("User signed out");
      break;
    case "TOKEN_REFRESHED":
      console.log("Token refreshed");
      break;
    case "USER_UPDATED":
      console.log("Profile updated");
      break;
  }
});
 
// Stop listening
unsubscribe();

// Check if authenticated
auth.isAuthenticated(); // boolean
 
// Get current access token
auth.getAccessToken(); // string | null

const auth = new GhaymaAuth({
  appSlug: "my-auth-app",
  serverKey: process.env.GHAYMA_AUTH_SERVER_KEY, // never in a browser
});
 
// The address travels per call, so one instance serves every user.
await auth.login({ email, password }, { clientIp });

POST /v1/{app-slug}/login
X-Ghayma-Server-Key: ghs_...
X-Ghayma-Client-IP: 203.0.113.7
Content-Type: application/json

try {
  await auth.register({ email, password }, { clientIp });
} catch (err) {
  if (err instanceof AuthError && err.code === "rate_limited") {
    setMessage(`Too many attempts. Try again in ${err.retryAfter}s.`);
    return;
  }
  throw err;
}

import { GhaymaAuth, AuthError } from "@ghayma/sdk/client";
 
try {
  await auth.login({ email: "[email protected]", password: "wrong" });
} catch (err) {
  if (err instanceof AuthError) {
    console.error(err.message);    // "invalid email or password"
    console.error(err.status);     // 401
    console.error(err.code);       // "request_failed" — see the table below
    console.error(err.retryAfter); // seconds to wait — 429 only
  }
}

import { useState, useEffect } from "react";
import { GhaymaAuth } from "@ghayma/sdk/client";
 
const auth = new GhaymaAuth({
  appSlug: "my-auth-app",
  storage: "localStorage",
});
 
function App() {
  const [user, setUser] = useState(null);
 
  useEffect(() => {
    // Check for existing session
    if (auth.isAuthenticated()) {
      auth.getUser().then(setUser).catch(() => setUser(null));
    }
 
    // Listen for auth changes
    return auth.onAuthStateChange((event) => {
      if (event === "SIGNED_OUT") setUser(null);
    });
  }, []);
 
  async function handleLogin(email: string, password: string) {
    const { user } = await auth.login({ email, password });
    setUser(user);
  }
 
  async function handleLogout() {
    await auth.logout();
    setUser(null);
  }
 
  if (!user) return <LoginForm onLogin={handleLogin} />;
  return <Dashboard user={user} onLogout={handleLogout} />;
}

import { GhaymaAuth } from "@ghayma/sdk/client";
 
// Client-side instance (browser) — never give this one a serverKey.
export const auth = new GhaymaAuth({
  appSlug: "my-auth-app",
  storage: "localStorage",
});

import { NextRequest, NextResponse } from "next/server";
import { cookies } from "next/headers";
import { GhaymaAuth, AuthError } from "@ghayma/sdk/client";
 
export async function POST(req: NextRequest) {
  const { email, password } = await req.json();
 
  // The visitor's IP, which Ghayma's edge writes to `X-Real-IP`
  // (see /guides/visitor-ip), forwarded so the rate limits count the
  // visitor and not this server.
  const clientIp = req.headers.get("x-real-ip") ?? undefined;
 
  // One instance per request — a session must never be shared between
  // concurrent users. serverKey comes from the injected env on Ghayma.
  const auth = new GhaymaAuth({
    appSlug: process.env.GHAYMA_AUTH_APP_ID!,
    storage: "memory",
  });
 
  try {
    // If your app enables 2FA, branch on the login result first — see
    // Two-Factor Authentication above.
    const session = await auth.login({ email, password }, { clientIp });
 
    const cookieStore = await cookies();
    cookieStore.set("auth_token", session.access_token, {
      httpOnly: true,
      secure: process.env.NODE_ENV === "production",
      sameSite: "lax",
      maxAge: 900,
    });
    cookieStore.set("refresh_token", session.refresh_token, {
      httpOnly: true,
      secure: process.env.NODE_ENV === "production",
      sameSite: "lax",
      maxAge: 604800,
    });
 
    return NextResponse.json({ user: session.user });
  } catch (err) {
    if (!(err instanceof AuthError)) throw err;
    // Pass 401s and 429s (with their Retry-After) back to the browser.
    return NextResponse.json(
      { error: err.message, code: err.code },
      {
        status: err.status,
        headers: err.retryAfter
          ? { "Retry-After": String(err.retryAfter) }
          : undefined,
      },
    );
  }
}