Authentication
What it is
Nodabase authentication is provided by GoTrue. nodabase.auth is the Node.js interface to it: email and password sign-up and sign-in, current-user lookups, session refresh, sign-out and a few account operations.
Your application calls the client; the client calls GoTrue. Every method returns a normalized user or { user, session } object, so your code works with one consistent shape no matter which call produced it.
How it works
Node.js application
|
v
nodabase.auth
|
v
GoTrue
|
v
authentication and session infrastructureThe application never assembles GoTrue requests itself. It passes credentials or a token to nodabase.auth, the client makes the HTTP call, and the response comes back normalized.
Configuration
NODABASE_AUTH_URL=http://localhost:9999
NODABASE_AUTH_URL points at GoTrue and defaults to http://localhost:9999. When your application runs inside the Nodabase platform, the binding is provided for you.
Unlike the other modules, auth is always present on the client — it is created even with no configuration, using the default URL.
Basic usage
Sign up
import { nodabase } from "nodabase";const { user, session } = await nodabase.auth.signUp({email: "you@example.com",password: "choose-a-strong-password",});
The returned session carries tokens only once the address is confirmed — with email auto-confirmation enabled in the installation, signUp hands back a usable session right away.
Sign in
const { user, session } = await nodabase.auth.signIn({email: "you@example.com",password: "choose-a-strong-password",});
Same shape back: the signed-in user and a session to keep.
Common operations
Get the current user
const user = await nodabase.auth.getUser(session.accessToken);
Refresh the session
const { session: refreshed } = await nodabase.auth.refreshSession(session.refreshToken);
A refresh returns a whole new session — keep the new tokens and let the old ones go.
Sign out
await nodabase.auth.signOut(session.accessToken);
Resolves to null on success.
Account operations
await nodabase.auth.updatePassword(session.accessToken, newPassword);await nodabase.auth.updateEmail(session.accessToken, newEmail);await nodabase.auth.resetPassword("you@example.com"); // sends a recovery emailawait nodabase.auth.verifyEmail({ token, email });
The two update calls return the updated user. resetPassword sends a recovery email and resolves to null; verifyEmail confirms the token from that email and returns { user, session }.
The session object
| Field | Meaning |
|---|---|
accessToken | identifies the user; pass it to the methods that need it |
refreshToken | obtains a new session when the access token expires |
tokenType | Bearer |
expiresIn | lifetime of the access token in seconds |
expiresAt | expiry as reported by GoTrue, when present |
Access tokens are bearer tokens: pass them to the client methods that accept one, and send them as Authorization: Bearer <accessToken> on your own API requests.
The user object
| Field | Meaning |
|---|---|
id, email | identity |
emailVerified | whether the address is confirmed |
name, firstName, lastName, username | profile fields from user metadata |
phone, phoneVerified | phone number and its confirmation state |
locale | locale from user metadata |
metadata | the full user_metadata object |
Important notes
- The client keeps no state of its own. Tokens are passed in on every call, so where sessions live — a cookie, memory, your own tables — is your decision.
authis the one module that is always present;db,cacheand the others only appear when their environment variable is set.- GoTrue's own policies apply: email confirmation, recovery emails and password rules behave as configured in the installation.
Handling errors
Failures throw NodabaseAuthError with a code and a status — branch on the code rather than parsing messages:
try {await nodabase.auth.signIn({ email, password });} catch (error) {console.error(error.code, error.message); // from GoTrue, or "AUTH_ERROR"}
Next steps
- Database — PostgreSQL through
nodabase.db - Cache — Redis-compatible caching through Dragonfly
- Overview — how the client and the services fit together
- Quickstart — run the platform