Authentication overview & token model
Any collection with type: "auth" gets password auth, refresh, and the
rest of the auth surface below for free — registration is just
POST .../records with password/passwordConfirm, there’s no separate
“register” endpoint. Session tokens are stateless HS256 JWTs signed with
app secret + record.tokenKey + authToken.secret — there’s no
server-side revocation list. Rotating a record’s tokenKey (which every
password or email change does) invalidates every outstanding session for
that record without a lookup table; rotating the app-wide AUTH_SECRET
invalidates every session at once, everywhere.
Token transport & revocation
Section titled “Token transport & revocation”A session token travels one of two ways: as a bearer Authorization
header (the default, and the only option for non-browser clients), or
as an HttpOnly cookie when cookie
sessions are enabled
server-side. tokenKey/AUTH_SECRET rotation still invalidates
sessions the way described above regardless of transport, but that was
previously the only way to end a session early — signing out was a
client-side-only affair, clearing the local store while the token
itself stayed valid until it expired on its own. _sessions tracking
(on by default) adds real server-side enforcement on top: POST auth-signout now revokes the current session rather than just
forgetting it locally, and cb.auth.sessions.revoke/revokeOthers/ revokeAll end sessions on demand. See
Sessions for the full
revocation model.
Cratebase vs better-auth
Section titled “Cratebase vs better-auth”Cratebase’s auth surface is scoped to what a consumer app needs, not every auth pattern a B2B SaaS might reach for eventually. Where better-auth covers both, this is roughly the split:
| Cratebase | better-auth | |
|---|---|---|
| Password auth | ✅ | ✅ |
| Email OTP / magic link | ✅ | ✅ (plugins) |
| OAuth2 social sign-on | ✅ 12 built-in presets + generic OIDC + custom | ✅ similarly broad |
| TOTP 2FA + backup codes | ✅ integrated with the existing MFA challenge | ✅ (plugin) |
| Passkeys / WebAuthn | ❌ deliberately deferred | ✅ (plugin) |
| SMS 2FA | ❌ deliberately deferred | ✅ (plugin) |
| SAML / enterprise SSO | ❌ deliberately deferred | ✅ (plugin) |
| Anonymous auth | ❌ deliberately deferred | ✅ (plugin) |
| Organizations / multi-tenancy | ❌ deliberately deferred — see Teams for the one primitive Cratebase does ship (app-level workspaces, not admin-dashboard access) | ✅ (plugin) |
| Impersonation, bans, sessions | ✅ built in | ✅ (plugins) |
| API keys | ✅ built in | ✅ (plugin) |
| Storage model | Postgres or SQLite, the same database as your app data — no separate auth service | Any SQL/NoSQL adapter, typically alongside your app’s own ORM |
The deferred rows aren’t a roadmap promise — they’re patterns a multi-tenant B2B product needs and a consumer app generally doesn’t. Cratebase would rather stay small than grow a plugin system to cover every one of them.