Client
Better Auth Ruby is an HTTP auth server plus a server-side Ruby API. Browser and native clients call the mounted Rack endpoint with normal HTTP requests.
Installation
Install the core gem for Rack apps:
gem "better_auth"For Rails apps, install the Rails adapter:
gem "better_auth-rails"Create Client Instance
Server-side Ruby code uses auth.api.
auth = BetterAuth.auth(
base_url: "http://localhost:3000/api/auth",
secret: ENV.fetch("BETTER_AUTH_SECRET"),
email_and_password: {enabled: true}
)Browsers call the mounted auth route:
await fetch("/api/auth/sign-in/email", {
method: "POST",
credentials: "include",
headers: {"content-type": "application/json"},
body: JSON.stringify({
email: "john@example.com",
password: "password123"
})
});Usage
Sign up:
curl -i http://localhost:3000/api/auth/sign-up/email \
-H 'content-type: application/json' \
-d '{"email":"john@example.com","password":"password123","name":"John"}'Sign in:
response = auth.api.sign_in_email(
body: {
email: "john@example.com",
password: "password123"
},
return_headers: true
)
cookie = response[:headers].fetch("set-cookie")Get the current session:
auth.api.get_session(headers: {"cookie" => cookie})Sign out:
auth.api.sign_out(headers: {"cookie" => cookie})Hooks
Ruby apps do not use reactive browser hooks. In Rails, use controller helpers for request-time session access.
class DashboardController < ApplicationController
include BetterAuth::Rails::ControllerHelpers
before_action :require_better_auth_session!
def show
@user = better_auth_user
end
endFetch Options
Browser requests that should keep the auth session must include credentials:
fetch("/api/auth/get-session", {
credentials: "include"
});Cross-origin apps must configure cookies and trusted origins on the server:
auth = BetterAuth.auth(
base_url: "https://api.example.com/api/auth",
trusted_origins: ["https://app.example.com"],
advanced: {
cross_subdomain_cookies: {
enabled: true,
domain: ".example.com"
}
}
)Disabling Default Fetch Plugins
The Ruby server has no built-in browser fetch plugin layer. Configure browser fetch behavior in your frontend HTTP client.
fetch("/api/auth/sign-in/email", {
method: "POST",
credentials: "include"
});Session Options
Use get_session when you need the current session and list_sessions when you need every active session for the user.
session = auth.api.get_session(headers: {"cookie" => cookie})
sessions = auth.api.list_sessions(headers: {"cookie" => cookie})Session expiration, refresh, freshness, cookie cache, secondary storage, and stateless sessions are configured on the server. See Session Management.
Disable Default Fetch Plugins
If your frontend client has redirect or retry middleware, disable it in that client. Better Auth Ruby only returns HTTP responses from the mounted Rack endpoint.
Disabling Hook Rerenders
Ruby does not provide reactive browser hooks. In Rails, controller helpers read the current session per request, and browser apps can refetch /get-session when needed.
Handling Errors
Server-side Ruby calls raise BetterAuth::APIError.
begin
auth.api.sign_in_email(body: {email: "john@example.com", password: "bad"})
rescue BetterAuth::APIError => error
error.status_code
error.message
endHTTP clients should branch on the response status.
const response = await fetch("/api/auth/sign-in/email", options);
if (!response.ok) {
const error = await response.json();
}Error Codes
BetterAuth::APIError exposes status_code, code, message, and headers.
rescue BetterAuth::APIError => error
error.code
endPlugins
Server plugins are configured in Ruby and may add routes that clients call over HTTP.
auth = BetterAuth.auth(
secret: ENV.fetch("BETTER_AUTH_SECRET"),
plugins: [
BetterAuth::Plugins.magic_link(
send_magic_link: ->(data, _request) { AuthMailer.magic_link(data).deliver_later }
)
]
)