Ferrum Family · Developer portal

Ferrum Nexus

Your gateway, open to developers.

The multi-user developer portal in front of Ferrum Edge. Providers publish APIs from OpenAPI specs, clients discover them, request access and issue their own credentials. Every approval, message and change is audited, and every gateway change happens server-side.

v0.3.0 Ferrum Edge v0.9.9 Node.js 22.14+ PolyForm Noncommercial
View on GitHub Quick Start Getting Started Guide
Status
v0.3.0Released October 1, 2026
Runs as
Web portal + backendTagged source build; build the image from docker/Dockerfile
Built with
React 19, Fastify 5Strict TypeScript; PostgreSQL, MySQL, SQLite or MongoDB
Ferrum Edge
Paired with v0.9.9Other Edge versions are unverified
v0.3.0 is the current release. It upgrades v0.2.0 and v0.1.0 Nexus databases with forward migrations. The paired Edge v0.9.9 upgrade requires a logical export and re-import into a fresh SQL gateway database. Back up both products together and rehearse the gateway import on a copy; the release notes state that CI does not exercise that import from v0.9.8. Pre-v0.1.0 Nexus databases must be recreated. Upgrade the gateway together with the portal, and run one active Nexus writer. The release notes list the supported pair and known limitations; see also release compatibility.
The Ferrum Nexus API catalog listing published APIs with their version, auth type and access status
Every published API a user may see, with its access status. Screenshots come from a portal seeded with demo data against a mock Ferrum Edge Admin API; a light theme ships too.
Capabilities

Everything Between a Spec and a Credential

Nexus owns accounts, approvals, messaging, branding, audit history and the catalog. Ferrum Edge keeps owning proxies, plugins, consumers and credentials.

OpenAPI in, proxy out

Publishing an OpenAPI spec creates the Edge proxy and its auth, access control, rate limit and CORS plugins on a staging path, then cuts over. A failed step rolls back what it created.

Approvals as ACL grants

Approving a request adds the API's ACL group to the client's gateway consumer; revoking removes it. Access is enforced by Edge, not only remembered by the portal.

Show-once credentials

Clients issue, rotate and revoke API keys, basic auth passwords and JWT secrets. Secrets are shown once and stored only on Edge; Nexus keeps a fingerprint and the last four characters.

Applications

One account can keep its integrations apart. Each application is its own gateway identity with its own approved APIs and credentials; account-level access remains the default.

Messaging and notifications

Client-to-provider and platform threads, bell notifications, broadcasts and transactional email through a durable outbox. v0.3.0 adds specification-change history and notices, plus OpenID Connect sign-in with PKCE; SMTP is needed for email delivery and most existing-account links.

Audit everything

Every state-changing action writes an audit row with actor, target and redacted details, committed with the change it describes and filterable from the admin area.

White-label branding

Portal name, logo, colours, typeface, corner radius, sidebar style and sign-in layout, previewed live in both themes before you save.

Safe sign-up

Optional email verification, open or closed registration, CAPTCHA that must pass its own challenge before it is saved, and a bootstrap token for the first super admin.

Any database

PostgreSQL, MySQL, SQLite and MongoDB share one logical schema with string UUID keys. SQLite is the default; MongoDB must run as a replica set.

Portal Tour

From Published Spec to First Request

Providers publish, clients discover and request, providers decide, and the gateway enforces.

Catalog and docs

Documentation rendered from the live spec

Clients read each API's operations straight from the published OpenAPI document, with the invoke URL beside them.

  • Operations, parameters, request bodies and schemas
  • Version, auth type and access status per API
  • Invoke URL and gateway path with one-click copy
Rendered OpenAPI documentation for a published API in Ferrum Nexus
Access requests

Clients justify, providers decide

A client asks for access with a justification. The provider approves or denies it with a note, and can revoke the grant later.

  • Approval adds nexus:api:<api_id>:approved to the consumer
  • Providers choose whether an API needs a request at all
  • In-app and email notifications on every decision
A provider reviewing a pending access request with the client's justification
Provider overview

What the gateway holds, with live usage

The configured listen path, upstream and rate limit sit beside usage read from Ferrum Edge on demand. Nexus stores no metrics of its own.

  • Requests by status and latency percentiles
  • Backend health from the gateway's circuit breaker
  • Edit rate limit, auth plugin, access policy, CORS and upstream
  • Test consumers for the provider's own APIs
Provider view of an API with its gateway configuration and usage read from Ferrum Edge
Credentials

Credentials clients control

Clients issue and manage their own gateway credentials, for their account or for one of its applications. The portal never keeps the secret.

  • API key, HTTP Basic and JWT credentials
  • A rotation returns the new secret once and retires the old one
  • Revoke immediately when a secret leaks
A client's gateway credentials with fingerprints and rotate and revoke actions
Messaging

Questions go to the person who published the API

Conversations stay inside the portal, with the API attached, instead of scattering across email.

  • Client and provider threads, optionally tied to an API
  • Platform threads with the admins for support
  • Rate limits and a daily budget per account keep spam out
A message thread between a client and a provider about an API
Administration

Run It Like a Product

Roles are ordered (Client, Provider, Admin, Super Admin) and enforced on the server, not just hidden in the UI.

Dashboard

Everything an account can reach, at a glance

Each role sees only the navigation and actions it may use.

  • Active grants and credentials for clients
  • Pending requests to review for providers
  • Portal-wide counts and recent audit activity for admins
  • Bell notifications for messages, decisions and broadcasts
The Ferrum Nexus dashboard with the notifications panel open
Branding and settings

Make the portal yours without a fork

Admins configure branding, email templates and mass email; super admins also control SMTP, CAPTCHA, the gateway address and admin roles.

  • Name, logo, colours, typeface, radius and sidebar style
  • Split or centered sign-in layout
  • God mode to revoke a grant, delete an API, disable a user or broadcast, with a recorded reason
Admin branding settings with a live preview of the portal in both themes
User management with roles and status filters
Users and roles. Change roles, disable and re-enable accounts, filtered by role, status and organization.
The audit log with filters
Audit log. Every state-changing action, filterable, with its JSON details one click away.
A branded split-layout sign-in page
Branded sign-in. Your logo and tagline; email verification and CAPTCHA are optional.
How It Works

A Portal in Front of the Gateway

A backend-for-frontend owns the portal and delegates the runtime to Ferrum Edge. The browser never calls the Edge Admin API.

BrowserClients, providers and admins use the portal SPA
Same-origin HTTPS
session + CSRF
Ferrum NexusChecks roles and ownership, writes the audit row
Admin API
short-lived JWT
Ferrum EdgeProxies, plugins, consumers and credentials
Approved
client traffic
Your APIsThe upstreams behind each published spec

One consumer per identity

Each account (nexus-user-<id>) or application (nexus-app-<id>) is one Ferrum consumer. A requestable API's access_control plugin allows only its approved group.

Only its own plugin configs

Nexus records the Edge config id of each plugin config it creates and never rewrites or deletes an operator's config of the same name.

Gateway truthfulness

Usage is read from Edge on demand. A periodic reconciliation pass notices when a rebuilt or retargeted gateway no longer holds the consumers and proxies Nexus stored.

Built With

Tech Stack

An npm workspace of three packages: the web SPA, the Fastify backend and zero-dependency shared TypeScript.

React 19Portal SPA
TypeScriptStrict, shared wire types
Vite + Tailwind CSS v4Build and styling
TanStackRouter, Query and Table
Radix UIAccessible primitives
Fastify 5Backend-for-frontend
Node.js 22.14+Runtime
4 databasesPostgreSQL, MySQL, SQLite, MongoDB
Get Started

Quick Start

There is no prebuilt Nexus image. Build from the release tag; the Compose stack pins the exact Edge image the release was tested with.

Node.js 22.14+ Docker Ferrum Edge v0.9.9

  1. Run the full stack with Compose

    bash
    git clone https://github.com/ferrum-edge/ferrum-nexus.git
cd ferrum-nexus
git checkout --detach v0.3.0

cp docker/docker-compose.example.yml docker-compose.yml
set -a
. ./release/compatibility.env
set +a
export NEXUS_SECRET_KEY=$(openssl rand -hex 32)
export NEXUS_DB_PASSWORD=$(openssl rand -hex 16)
export FERRUM_ADMIN_JWT_SECRET=$(openssl rand -hex 32)
export FERRUM_BASIC_AUTH_HMAC_SECRET=$(openssl rand -hex 32)
docker compose up -d

    This runs Nexus, PostgreSQL and Ferrum Edge v0.9.9. The portal is at http://127.0.0.1:8787 and the gateway's proxy listener at http://127.0.0.1:8000. Keep the secrets stable for the life of the stack.

  2. Or run from source against your own gateway

    bash
    npm ci
cp .env.example .env
# set NEXUS_SECRET_KEY and FERRUM_ADMIN_JWT_SECRET (32+ characters each)
npm run migrate
npm run dev       # backend :8787, web :5173

    Open http://127.0.0.1:5173. SQLite is the default database. FERRUM_ADMIN_JWT_SECRET and FERRUM_NAMESPACE must match the running gateway.

  3. Create the super admin and publish an API

    bash
    docker compose logs nexus   # Compose: prints the bootstrap token

    The first account to register becomes the super admin and must present the bootstrap token: set NEXUS_BOOTSTRAP_TOKEN, or copy the one the server prints at startup. Then follow the getting-started walkthrough to publish an API, approve access and call it through Edge. Before production, read operations for TLS, backups, upgrades and the single-writer model.

VariableDefaultDescription
NEXUS_SECRET_KEY—Master secret; session signing and settings encryption keys are derived from it (required, 32+ characters)
FERRUM_ADMIN_URLhttp://127.0.0.1:9000Ferrum Edge Admin API base URL, server-side only. A plain http:// URL on a non-loopback host needs FERRUM_ADMIN_ALLOW_INSECURE_HTTP=true
FERRUM_ADMIN_JWT_SECRET—Shared secret for short-lived Admin API JWTs; must match the gateway (required, 32+ characters)
FERRUM_NAMESPACEnexusGateway namespace Nexus manages; must equal the gateway's own FERRUM_NAMESPACE
FERRUM_GATEWAY_PUBLIC_URL—Public origin of the gateway's proxy listener, used to build each API's invoke URL
NEXUS_BOOTSTRAP_TOKENgeneratedToken the first registration must present to become super admin (16+ characters); set it when running more than one instance
NEXUS_PUBLIC_URLhttp://127.0.0.1:5173Public origin of the portal, used in emails and CORS
NEXUS_DB_DRIVERsqlitesqlite, postgres, mysql or mongodb (with NEXUS_DB_URL)
NEXUS_PORT / NEXUS_WEB_PORT8787 / 5173Backend bind port and Vite dev-server port
NEXUS_COOKIE_SECUREtrueSecure session cookies and HSTS. Set false only for plain-http local use
The Ferrum Family

Works With the Rest of the Stack

Licensing

Ferrum Nexus is licensed under PolyForm Noncommercial 1.0.0 for personal, research, educational and nonprofit use. A commercial license is available for commercial use.

View on GitHub Licensing Details