Skip to main content
The additionalFields plugin lets you attach typed custom data to users and sessions without writing migrations. Fields are stored in the metadata JSON column of theauth_users and theauth_sessions.

Install

Ships inside @glinr/theauth/auth, no extra packages needed.

Setup

Define a schema once when creating your theAuth instance:

Reading and writing user fields

setUserFields merges with existing fields. Previously stored keys not present in the update are preserved. It throws if validation fails or the user does not exist.

Reading and writing session fields

Validation

Validate a field map before writing, or in a request handler:
Rules enforced during validate() (and automatically on every setUserFields / setSessionFields call):
  • Required fields must be present in the map you pass. Because setUserFields and setSessionFields validate the update itself (not the merged result), a schema with required: true fields means every write must include them.
  • Field values must match the declared type.
  • Fields not in the schema are rejected.

Field types

REST endpoints

GET example

PUT example

Returns 422 when validation fails. Returns 404 when the user does not exist. The endpoints require an authenticated user, but they do not check that the userId is the caller’s own, so any signed-in caller can read or write another user’s fields. Put your own ownership or admin check in front of them. GET returns the schema defaults for an unknown user ID rather than a 404.

Validate example

The status is 200 when valid and 422 when not. schema must be "user" or "session". Only the user fields have REST read and write endpoints, session fields are read and written through the module (getSessionFields, setSessionFields).

Schema reference

Storage

No database migrations are needed. User fields are stored under user.metadata.additionalFields and session fields under session.metadata.additionalFields. Other metadata keys written by the core system or other plugins are not modified.

Hooks

Lifecycle hooks you can attach to your instance.

Custom session

Store extra data on a session record.

Database

Supported databases and schema overview for theAuth.

Organizations

Organizations with roles and per-org metadata.
Last modified on October 18, 2026