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 infrastructure

The 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

env
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

js
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

js
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

js
const user = await nodabase.auth.getUser(session.accessToken);

Refresh the session

js
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

js
await nodabase.auth.signOut(session.accessToken);

Resolves to null on success.

Account operations

js
await nodabase.auth.updatePassword(session.accessToken, newPassword);
await nodabase.auth.updateEmail(session.accessToken, newEmail);
 
await nodabase.auth.resetPassword("you@example.com"); // sends a recovery email
await 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

FieldMeaning
accessTokenidentifies the user; pass it to the methods that need it
refreshTokenobtains a new session when the access token expires
tokenTypeBearer
expiresInlifetime of the access token in seconds
expiresAtexpiry 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

FieldMeaning
id, emailidentity
emailVerifiedwhether the address is confirmed
name, firstName, lastName, usernameprofile fields from user metadata
phone, phoneVerifiedphone number and its confirmation state
localelocale from user metadata
metadatathe 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.
  • auth is the one module that is always present; db, cache and 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:

js
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