proofgeist/better-auth-setup

Setup

Prerequisites

• OData enabled on FileMaker Server
• API credentials with fmodata privilege enabled
• Read/write access to the better-auth tables
• Full Access credentials available for schema migration (can differ from runtime credentials)

Install packages

pnpm add @proofkit/better-auth @proofkit/fmodata

Configure auth.ts

import { betterAuth } from "better-auth";
import { FMServerConnection } from "@proofkit/fmodata";
import { FileMakerAdapter } from "@proofkit/better-auth";

const connection = new FMServerConnection({
  serverUrl: process.env.FM_SERVER_URL!,
  auth: {
    username: process.env.FM_USERNAME!,
    password: process.env.FM_PASSWORD!,
  },
});

const db = connection.database(process.env.FM_DATABASE!);

export const auth = betterAuth({
  database: FileMakerAdapter({ database: db }),
  // add plugins, social providers, etc.
});

FileMakerAdapter accepts a FileMakerAdapterConfig:

• database (required) -- an fmodata Database instance
• debugLogs (optional) -- enable adapter debug logging
• usePlural (optional) -- set true if table names are plural

The adapter maps Better Auth operations (create, findOne, findMany, update, delete, count) to OData requests via db._makeRequest. It does not support JSON columns, native dates, or native booleans -- all values are stored as strings/numbers.

Alternative: Data API key (OttoFMS 4.11+)

const connection = new FMServerConnection({
  serverUrl: process.env.FM_SERVER_URL!,
  auth: {
    apiKey: process.env.OTTO_API_KEY!,
  },
});

OData must be enabled for the key.

Core Patterns

1. Initial migration

After configuring auth.ts, run the migration CLI to create tables and fields in FileMaker:

npx @proofkit/better-auth migrate

The CLI:

1. Loads your auth.ts config (auto-detected or via --config <path>)
2. Calls getSchema() from better-auth/db to determine required tables/fields
3. Fetches current OData metadata via db.getMetadata()
4. Computes a diff: tables to create, fields to add to existing tables
5. Prints the migration plan and prompts for confirmation
6. Executes via db.schema.createTable() and db.schema.addFields()

Only schema is modified. No layouts or relationships are created.

If your runtime credentials lack Full Access, override for migration only:

npx @proofkit/better-auth migrate --username "admin" --password "admin_pass"

Skip confirmation with -y:

npx @proofkit/better-auth migrate -y

2. Adding plugins and re-migrating

When you add a Better Auth plugin (e.g. twoFactor, organization), it declares additional tables/fields. After updating auth.ts:

import { betterAuth } from "better-auth";
import { twoFactor } from "better-auth/plugins";
import { FMServerConnection } from "@proofkit/fmodata";
import { FileMakerAdapter } from "@proofkit/better-auth";

const connection = new FMServerConnection({
  serverUrl: process.env.FM_SERVER_URL!,
  auth: {
    username: process.env.FM_USERNAME!,
    password: process.env.FM_PASSWORD!,
  },
});

const db = connection.database(process.env.FM_DATABASE!);

export const auth = betterAuth({
  database: FileMakerAdapter({ database: db }),
  plugins: [twoFactor()],
});

Re-run migration:

npx @proofkit/better-auth migrate

The planner diffs against existing metadata, so only new tables/fields are added. Existing tables are left untouched.

3. Troubleshooting privilege errors

When migration fails with OData error code 207, the account lacks schema modification privileges. The CLI outputs:

Failed to create table "tableName": Cannot modify schema.
The account used does not have schema modification privileges.
Use --username and --password to provide Full Access credentials.

Fix: provide Full Access credentials via CLI flags. These are only used for migration, not at runtime.

Common Mistakes

[CRITICAL] Using better-auth CLI instead of @proofkit/better-auth

Wrong:

npx better-auth migrate

Correct:

npx @proofkit/better-auth migrate

The standard better-auth CLI does not know about the FileMaker adapter and produces: ERROR [Better Auth]: filemaker is not supported. If it is a custom adapter, please request the maintainer to implement createSchema. The @proofkit/better-auth CLI loads your auth config, extracts the Database instance from the adapter, and handles migration via fmodata's schema API.

Source: apps/docs/content/docs/better-auth/troubleshooting.mdx

[HIGH] Missing Full Access credentials for schema migration

Wrong:

# Using runtime credentials that only have fmodata privilege
npx @proofkit/better-auth migrate
# Fails with OData error 207: Cannot modify schema

Correct:

npx @proofkit/better-auth migrate --username "full_access_user" --password "full_access_pass"

Schema modification (db.schema.createTable, db.schema.addFields) requires [Full Access] privileges. Standard API accounts with fmodata privilege can read/write data but cannot alter schema. The CLI accepts --username and --password flags to override credentials for migration only.

Source: packages/better-auth/src/cli/index.ts, packages/better-auth/src/migrate.ts

[HIGH] Removing fields added by migration

Wrong:

Manually deleting "unused" fields from better-auth tables in FileMaker

Correct:

Keep all fields created by migration, even if you don't plan to use them

Better Auth expects all schema fields to exist at runtime. The adapter issues OData requests that reference these fields. Removing them causes runtime errors when Better Auth attempts to read or write those columns.

Source: apps/docs/content/docs/better-auth/installation.mdx

[HIGH] Forgetting to re-run migration after adding plugins

Wrong:

// Added twoFactor() plugin to auth.ts but did not re-run migration
export const auth = betterAuth({
  database: FileMakerAdapter({ database: db }),
  plugins: [twoFactor()],
});
// Runtime errors: tables/fields for twoFactor don't exist

Correct:

# After adding any plugin to auth.ts, always re-run:
npx @proofkit/better-auth migrate

Each plugin declares additional tables and fields via getSchema(). The migration planner diffs the full schema (including plugins) against current OData metadata. Without re-running, the new tables/fields don't exist and Better Auth throws at runtime.

Source: apps/docs/content/docs/better-auth/installation.mdx

References

• fmodata-client -- Better Auth uses fmodata Database under the hood for all OData requests. FMServerConnection and database() must be configured before FileMakerAdapter can work. The adapter calls db._makeRequest() for CRUD and db.schema.* for migrations.