Compatibility

The contract

HTTP behavior targets better-auth@1.7.7: the same endpoints, request and response shapes, status codes, error codes, redirects and cookie attributes. The official TypeScript client therefore works against a Alibi server without changes, and so do existing database rows and password hashes (scrypt in the TypeScript format).

Newer upstream documentation may describe behavior added after 1.7.7; it is outside the target until the pin moves.

Rust releases use independent Semantic Versioning and record the exact upstream target separately, so fixes can ship independently while retaining the upstream contract. See the release policy for versioning and compatibility rules.

How parity is verified

Parity is established by one mechanism: a differential suite that runs the official client against both the pinned TypeScript runtime and this implementation, then compares everything they return and store.

• Scenarios run sequentially against fresh state on each server. Values, response shapes, status codes, redirects and cookies are compared; cookie security attributes are compared without exceptions.
• Generated identifiers and opaque tokens are compared through a bijection (repeated references and token rotation must agree). Dates must be valid and lifetimes agree within a small execution tolerance.
• Password scenarios import real hashes produced by each runtime into both stores and exercise sign-in, Unicode normalization and credential replacement.
• A software authenticator produces genuine WebAuthn signatures for the passkey scenarios; encrypted account and session cookies are authenticated with the published decoders; Chromium checks real browser cookie behavior.
• Negative controls prove the comparator catches drift.
• The route inventory test fails when the router’s routes differ from capabilities.json, which lists every upstream route together with the scenarios proving it. All 151 inventoried routes are implemented.

Unit and integration tests check the Rust implementation on its own terms and do not claim parity. The full contract and how to run it are in the compatibility guide; the audit of the target is in the upstream target audit.

Native Rust APIs

Everything that is not an HTTP contract is native and may differ from TypeScript:

Area	Native design
Schema	Application-owned models and AuthSchema, generated by the CLI, instead of adapter-managed tables
Configuration	Typed AuthConfig and per-plugin config structs; numbers that mirror JavaScript numbers are f64
Plugins	The AuthPlugin trait (Writing a plugin)
Callbacks	Async trait objects with a CallbackContext (delivery, hooks, resolvers)
Server API	Typed dispatch_endpoint operations instead of auth.api.* (Server-side calls)
Integrations	Axum and Poem adapters and extractors
Storage	SQLx and SeaORM stores, no-database mode, secondary storage
Extra operations	openapi_spec_with_native_extensions() lists Rust-only operations

Where Rust needs a different shape, behavior stays observably the same on the wire: for example AuthError::Api produces the same {code, message} envelope as an APIError.

Implemented

• All core routes: sign-up/sign-in, sessions, user and account management, password reset, email verification, OAuth and token endpoints.
• All bundled plugins: admin, anonymous, bearer, CAPTCHA, custom session, device authorization, email OTP, Have I Been Pwned, JWT, last login method, magic link, multi-session, OAuth popup, OAuth proxy, One Tap, one-time token, OpenAPI, organization (teams, dynamic roles), passkey, phone number, SIWE, two-factor, username — plus the API-key and passkey packages.
• All 36 built-in social providers and generic OAuth/OIDC with discovery.
• Cross-cutting behavior: managed secrets, dynamic base URL and trusted origins, cookie caches (compact, JWT, JWE), stateless sessions, secondary storage, rate limiting with shared backends, background tasks, database and endpoint hooks, additional fields.

Out of scope

These upstream packages are explicitly not implemented and have no planned work:

Package	What it is
@better-auth/oauth-provider, @better-auth/mcp, @better-auth/cimd	Acting as an OAuth authorization server, MCP, client-ID metadata documents
@better-auth/sso	Enterprise SSO (OIDC/SAML provider management)
@better-auth/scim	SCIM provisioning
@better-auth/stripe	Stripe subscriptions
@better-auth/i18n	Translated error messages
@better-auth/expo, @better-auth/electron	Mobile and desktop client integrations

Alibi can consume OAuth/OIDC providers (including enterprise IdPs through Generic OAuth); it does not act as one. Redis storage and native framework integrations are covered separately from the upstream profiles.

Known boundaries

• Native token encoding. Rows written by early versions of this Rust implementation use an older OAuth-token encoding; see Legacy OAuth token conversion.
• Concurrent device decisions and a few other races retain the behavior measured on 1.7.6, unchanged by the 1.7.7 delta, including its edge cases.
• The TypeScript generic-OAuth client helper signIn.oauth2 is not served; use signIn.social (Generic OAuth).

Upgrading from 1.7.6

1.7.7 separates OAuth state, proxy state, proxy packages, and proxy profiles by encryption purpose. Upgrade servers sharing the verification store and OAuth proxy participants together. Request new Magic Links and restart pending OAuth flows: old verification identifiers and ciphertexts are deliberately rejected. Existing account credentials, password hashes and session records need no migration for this release change.

Checking a deployment

GET /api/auth/open-api/generate-schema (with the OpenAPI plugin) or the HTTP API reference lists exactly the routes your instance serves. Run the differential suite locally with ./scripts/compat.sh (Contributing).

Frontend

Use the official Better Auth client and frontend documentation.