melody-auth: an OAuth server you can run on Workers or on your own Node box

Two deployment shapes, one server

The pitch in the README is short enough to hold in your head. Melody Auth is a turnkey OAuth and authentication system, and it can be deployed in two ways.

On Cloudflare, using Workers, D1 and KV, which the README frames as deployable in minutes and as minimising infrastructure and DevOps overhead. On your own infrastructure, self-hosted with Node.js, Redis and PostgreSQL, which it describes as giving full control over your data and infrastructure.

That pairing is the reason to look at this project at all. Identity servers are usually a single opinionated deployment, and the interesting engineering question is how much of the product survives when the storage layer changes. Here, the same feature set is offered on a relational database with a cache, and on a platform with an embedded SQL database and a key-value store. The policy engine, the OAuth endpoints, the admin panel and the SDKs are the same.

The cost of that flexibility is visible in the feature list, because some capabilities are explicitly marked as Node.js only. SAML SSO sign-in is labelled for the Node.js environment only, and so is the raw SMTP mailer option, with SendGrid, Mailgun, Brevo, Resend and Postmark offered on both targets. If you deploy on Cloudflare and need SAML, that decision ends the evaluation.

The audience is a product team that wants to run authentication itself, with the front-end SDKs, the embedded API and the admin panel included, rather than assembling a login flow from an identity provider's hosted pages.

The OAuth surface is broad and specific

The feature list in the README is long, and its organisation tells you how the system is designed.

The OAuth 2.0 layer covers authorize, token exchange, refresh token revoke, app consent, app scopes, user info retrieval and openid configuration. The authorization layer is the everyday one: sign-in, passwordless sign-in, sign-up, sign-out, email verification, password reset, role-based access control, user attributes, account linking and localization.

External identity providers are a separate group. Social sign-in covers Google, Facebook, GitHub, Discord and Apple. There is also an OIDC auth provider sign-in and the SAML SSO sign-in marked as Node.js only.

Multi-factor authentication is the longest list in the document, and it is the one that reads like a real product rather than a checklist. Email MFA, OTP MFA, SMS MFA, self enrollment, passkey enrollment, recovery codes, and a remember device option valid for 30 days. Passkeys and recovery codes sit next to SMS, which is a combination you rarely see.

Three smaller groups are worth naming because they are the ones teams forget. Brute-force protection logs sign-in attempts, password reset attempts, and the attempts for each MFA channel, email verification and change email. JWT support includes RSA256 based authentication and a JWT secret rotation path. And the logging group covers logger level, email logs, SMS logs and sign-in logs, which is the raw material for the admin panel's log management screens.

Policies are named flows, including per-provider SSO triggers

The policy list is the part of the design that most distinguishes this from a typical login library, and it is easy to skim past because it reads as a list of names.

The policies are sign_in_or_sign_up, update_info, change_password, change_email, reset_mfa, manage_passkey, manage_recovery_code, plus two parameterised entries, saml_sso_[idp_name] and oidc_sso_[provider_name]. Each one names an authentication flow that the front end can trigger.

The parameterised entries are the interesting part. Instead of a separate endpoint per identity provider, the flow is selected by naming the provider, which means a front-end SDK can initiate a SAML or OIDC redirect by passing the provider name it wants. The README links the SAML and OIDC documentation with anchors on exactly this trigger, and the policy list is what the front end switches on.

Read together with the SDKs, the mechanism becomes clear. The React, Angular, Vue and web packages are published on npm as @melody-auth/react, @melody-auth/angular, @melody-auth/vue and @melody-auth/web, and the README describes them as SDKs to integrate PKCE-based authentication into your front-end application. So the flow is: the front end calls the SDK, the SDK starts a policy flow, the server runs the OAuth 2.0 authorize and token exchange, and the result comes back as tokens.

There is a second path for applications that cannot redirect away. The Embedded Auth API is for embedding authentication flows directly inside your application, with its own Swagger endpoint separate from the server-to-server API, and an example repository for it.

The admin panel is also the reference implementation

The admin panel is described in the README as both a tool for managing resources and a full-stack implementation example, and the links to a Next.js full stack implementation example point back at the admin-panel directory of this same repository. That is a deliberate choice: the panel is a real consumer of the server-to-server REST API, so it cannot drift from it.

The panel's capabilities cover the operational surface. You can view configurations, manage users including invites and impersonation, manage user attributes, manage apps with app-level MFA configuration and app banner configuration, and manage scopes, roles, organizations and SAML SSO identity providers. There is log management, and access to the panel itself is controlled by custom roles, with the documentation pointing at role-based access for the admin panel.

The server-to-server REST API is the other half. It is described as being for backend integrations, and it has its own Swagger page, distinct from the embedded auth Swagger. The two APIs are separated by audience: one for machine-to-machine work inside your backend, one for the browser.

The examples list is a good guide to which stacks the SDKs are expected to work with: a Vite React example, an Angular example, a Vite Vue example, a Next.js full stack implementation, a Next.js Auth.js example, a React Native example, a vanilla JavaScript example and the embedded auth example, plus a live demo site. That spread is a decent proxy for how much integration work a team is signing up for, since the SDK surface has to survive React Native and vanilla JavaScript as well as the mainstream frameworks.

A monorepo with three things you can run

The repository layout explains how the project is put together. At the top level there are server/ for the auth server, admin-panel/ for the management interface, sdks/ for the front-end packages, shared/ for code used across them, docs/ for the documentation site, devops/ for deployment material, plus a .claude/ directory, a CLAUDE.md file and an .eslintrc.json.

The root package.json is where the development workflow is defined, and three scripts tell you most of the story. The dev script runs the server and the admin panel together:

    "lint:check": "eslint ./ --ext .ts,.tsx,.js,.cjs",
    "docs:build": "vuepress build docs",
    "s2s:generate": "cd server && npm run swagger:generate:s2s && cd ../admin-panel && npm run service:generate"

The third of those is the one to understand. The server-to-server API client used by the admin panel is generated, and the script that produces it also regenerates the Swagger definition on the server side. That means the panel's typed service and the server's API description come from one place, and a change to the API surfaces in the panel as a type error rather than a runtime failure. It is the difference between an admin panel that is an example and one that is generated from the contract.

The docs are a VuePress site, built with vuepress build docs and developed with vuepress dev docs, and the documentation the README links lives at auth.valuemelody.com. The package version is 1.3.8 in package.json, matching the newest release tag, and the licence is MIT with the LICENSE file in the repository root.

What to check before you commit

A few practical points, some of them the project's own warnings.

The maintenance picture is good. Releases v1.3.6, v1.3.7 and v1.3.8 landed in August 2025, November 2025 and March 2026, the repository is not archived, and the last push was on 2026-10-19, so work continues between tags. For a project that is meant to hold credentials, that cadence matters more than in most libraries.

The README carries a disclaimer that deserves attention: all French translations provided in the project have been generated by AI, and the README asks that they be reviewed carefully for accuracy before use. For an authentication product, translated error messages and instructions that a user follows to recover an account are exactly the wrong place to accept unreviewed machine output. If you serve French users, treat those strings as a to-do rather than a feature.

The Node.js only markers for SAML SSO and SMTP are the other thing to check, because they determine whether one deployment target or both are viable for you. The full list of dependencies also lives in the documentation, and the choice of mailer and SMS provider, Twilio being the listed SMS option, is a decision with privacy and cost consequences rather than a technical one.

And the README contains no installation steps at all. It links to the setup and configuration pages on the documentation site for the auth server, the server-to-server API, the admin panel and the embedded auth API. So the first hour with this project is spent in the documentation, not in the terminal.

Editorial conclusion

melody-auth fits a team that wants to own its identity server, that is willing to run one on Cloudflare's edge stack or on its own Node.js infrastructure, and that needs the full OAuth 2.0 surface rather than a login widget. It is the wrong choice if you need SAML SSO or SMTP email on Cloudflare, since the README marks both as Node.js only, and it is the wrong choice if you want a vendor-hosted identity service, because the whole point here is that you run it. Before adopting, read the feature overview in docs/feature-overview.md, confirm the provider support you need for the deployment target, and check the release you install, since the newest tag is v1.3.8 from 2026-03-20 while the last push was on 2026-10-19.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. ValueMelody/melody-auth on GitHub