Use the documented configuration, generators and host hooks when integrating AddAuth. Check the release notes before updating a 0.x application.
This reference describes the published 0.5.1 integration surface. It does not announce a 1.0 release or a new support commitment. The maintained security support policy names the release line receiving fixes.
Supported environments
| Boundary | Verified scope |
|---|---|
| Ruby and Rails | Ruby 3.3, 3.4 and 4.0 with Rails 8.0 and 8.1. Use patched releases on maintained Ruby series. A permissive gem dependency is not evidence for an untested future Rails line. |
| Authentication database | SQLite and PostgreSQL have real store/request contracts. User, Session and installed AddAuth records must share one connection pool. Other adapters require their concurrency and rollback contracts to be verified. |
| Primary keys | Version 0.5.0 supports integer keys, PostgreSQL UUID keys and mixed user/session schemas. Every new AddAuth table honors Rails’ primary-key preference. Older packages require integer sessions; see the primary-key guide. |
| Jobs | Durable Active Job delivery is required in production. Local acceptance covers Sidekiq/Redis and Solid Queue with a separate queue database. The queue recipe describes the boundary. |
| Abuse counters | A shared store must atomically initialize and increment counters with expiry across processes. Solid Cache is unsuitable for this role; use the separate counter configuration. |
| Browsers | Local Chrome acceptance covers Turbo, JavaScript without Turbo, permitted no-JavaScript paths and virtual WebAuthn. Physical devices, hybrid ceremonies, other browsers and assistive technology need host-specific verification. |
Application integration surface
| Surface | Use and limits |
|---|---|
AddAuth.configure | The settings, callbacks, units and defaults in Configuration. Keep eligibility, trusted recovery addresses and resource authorization in the host. |
| Rails authentication integration | The generators extend the stock User, Session and Authentication concern. Preserve the generated inclusion order and hardened cookie/session hooks. Use require_add_auth_authentication to protect management routes in hosts that allow anonymous pages. |
| Reauthentication | require_elevated_session(purpose:, **options) guards navigation. with_elevated_session(purpose:) { ... } rechecks proof while performing the database mutation. Follow the complete write example; host authorization is still required. |
| Lifecycle | AddAuth::Rails::UserLifecycle invalidates proofs on normal password/address updates. Updates that skip callbacks need an explicit host invalidation procedure. Do not call its private callback as an API. |
| Routes and generated UI | The enabled paths and generators in Generators & commands. Ejected files remain host-owned; retain the baseline manifest and review upstream changes. There is no add_auth_for routing DSL or multi-realm registry. |
| Adapters | Documented digest and challenge contracts are extension points. WebAuthn signature verification is supplied by the WebAuthn library. Password verification uses the host’s Rails API or the explicit, reviewed legacy profile in the password migration guide. |
| Test helpers | AddAuth::Testing.delivered_link(mail, purpose:) and with_virtual_authenticator(driver, **options) { ... } are plain Ruby helpers. See Testing your integration. No framework-specific sign-in shortcut is promised. |
Optional migration and native contracts
See the lifecycle, provider, mobile and migration guides for their enabled routes, configuration and host responsibilities. These capabilities remain optional and do not promise every Devise module, arbitrary realms or general API-key management.
Results and monitoring
AddAuth::Result exposes success?, failure?, user, strategy, credential, reason, session and grant. Result inspection omits credential material; associated objects can still contain sensitive state. Never serialize a whole Result into logs or a public response. Internal failure reasons are mapped to deliberately generic public messages.
Use the documented maintenance and delivery events for monitoring. A completed bounded pass does not establish an empty backlog. Doctor checks configuration and known incompatibilities; its sequential cache probe cannot certify concurrent behavior or a live deployment.
Avoid coupling to internals
AddAuth::Rails::Runtime, store classes, private lifecycle callbacks, job payloads, cookie/token encodings and persistence implementation details are not general extension APIs. The plain Ruby Core separates policy from Rails; that architecture does not promise standalone packaging or compatibility for every constructor. Open a focused issue when a documented hook cannot support a reusable host need.
Next, use the upgrade rehearsal before changing an installed version.