@namoidhq/js

@namoidhq/js is a small, dependency-light browser/JS SDK for working with NamoID's hosted login and reading your environment's public auth configuration. It's a convenience layer over the public endpoints — your server-side OIDC token exchange should still use a standard OIDC library (see Other OIDC clients).

• Package: @namoidhq/js
• Module: ES module, ships TypeScript types

Install

npm install @namoidhq/js

Create a client

import { createNamoIDClient } from "@namoidhq/js";

const namoid = createNamoIDClient({
  publishableKey: "namoid_auth_pk_live_…", // required
  // apiBaseUrl defaults to https://api.namoid.in
  // hostedLoginBaseUrl defaults to apiBaseUrl
});

NamoIDClientOptions:

Option	Required	Default	Purpose
publishableKey	yes	—	Your auth publishable key (namoid_auth_pk_…)
apiBaseUrl	no	https://api.namoid.in	API origin
hostedLoginBaseUrl	no	apiBaseUrl	Hosted-login origin
fetcher	no	global fetch	Custom fetch implementation

Read the auth config

client.auth.getConfig() fetches your environment's public auth configuration — the enabled sign-in methods, access mode, MFA mode, branding, and signup requirements — sent with the X-API-Key header. Use it to render the right UI before redirecting:

const config = await namoid.auth.getConfig();
// config.signin_methods, config.access_mode, config.mfa_mode, …

Build or redirect to hosted login

client.hostedLogin.getUrl(options) returns a fully-formed authorization URL; client.hostedLogin.redirect(options) navigates the browser to it.

namoid.hostedLogin.redirect({
  clientId: "idpc_live_…",
  redirectUri: "https://your-app.example/auth/callback",
  scope: "openid email profile", // default
  state,                         // CSRF state you generate + verify
  nonce,                         // OIDC nonce you generate + verify
  codeChallenge,                 // PKCE challenge
  codeChallengeMethod: "S256",
  mode: "signin",                // "signin" | "signup" | "waitlist"
});

HostedLoginUrlOptions covers clientId, redirectUri, scope, state, nonce, codeChallenge, codeChallengeMethod ("S256" recommended), mode, and extraParams. redirect() throws a NamoIDError if called outside a browser.

Errors

Failures throw NamoIDError with status, code, and detail, so you can branch on the specific failure.

When to use this vs an OIDC library

Use @namoidhq/js for the front-channel: reading config and sending the user to hosted login from the browser. Use a standard OIDC library on your server to exchange the authorization code for tokens and validate them — NamoID is a conformant provider, so any of them work. For Next.js route handlers, @namoidhq/nextjs wraps that callback work. For React apps, @namoidhq/react wraps this SDK in components and hooks.