Introduction

This project is independent and is not affiliated with, maintained by, or endorsed by the Better Auth project.

Better Auth Ruby is a Ruby/Rack port of Better Auth. It keeps the upstream HTTP route surface, cookie names, JSON keys, option concepts, and plugin model where that maps cleanly to Ruby, while exposing an idiomatic server API through BetterAuth.auth(...).

What This Port Provides

• A framework-agnostic Rack core gem: better_auth
• A Rails adapter gem: better_auth-rails
• A Hanami adapter gem: better_auth-hanami
• Email/password auth, social OAuth routes, sessions, cookies, hooks, and rate limiting
• PostgreSQL, MySQL, memory, and Rails ActiveRecord persistence paths
• The upstream-style plugin system with Ruby plugin modules
• Server-side API calls through auth.api

Current Status

This port is usable for server-side Ruby flows, but it is still catching up to the full upstream surface. The implementation plan and parity notes live in:

• .docs/plans/2026-04-25-better-auth-ruby-port.md
• .docs/features/upstream-parity-matrix.md

The short version:

• Core Rack auth and Rails, Sinatra, and Hanami mounting are implemented.
• Most server-side plugins have Ruby implementations with local tests, including SSO, SCIM, Stripe, API key, OAuth Provider, and Dub.
• OpenAPI generation is supported with upstream base-route inventory, rich schemas, and Scalar reference output.

Packages

gem "better_auth"

# Rails apps usually want this adapter package instead:
gem "better_auth-rails"

# Hanami 2.3+ apps can use:
gem "better_auth-hanami"

How It Fits Together

BetterAuth.auth(options)
  -> BetterAuth::Context
  -> BetterAuth::RackApp
  -> BetterAuth::Router
  -> BetterAuth::Endpoint / BetterAuth::API
  -> BetterAuth::Cookies / BetterAuth::SessionStore
  -> BetterAuth::Adapters::{Memory, Postgres, MySQL, Rails, Hanami}
  -> BetterAuth::Plugins::*

Rails and Hanami integrations wrap the same core Rack auth object. They do not reimplement auth in controllers or actions.

Next Steps

Start with Installation, then pick either the Rack integration, Rails integration, or Hanami integration.