Authentication API

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/src/lib/auth.ts
• packages/contract/src/contract/auth.ts
• apps/api/src/index.ts
• README.md
• packages/contract/src/contract/index.ts
• apps/api/src/handlers/orpc.ts
• apps/api/src/handlers/openapi.ts

The Authentication API provides user management functionalities, including sign-up, sign-in, and session management. It is built using the better-auth library, which is integrated into the Hono web server. The system uses a contract-first approach, with API endpoints and schemas defined in the @contract-based-monorepo/contract package, ensuring type safety between the frontend and backend.

The authentication mechanism is configured to use an email and password strategy and persists data to a PostgreSQL database via the Drizzle ORM. It also integrates with OpenAPI to provide interactive API documentation.

Sources: README.md, apps/api/src/lib/auth.ts:6-8, packages/contract/src/contract/auth.ts

Architecture Overview

The authentication system is composed of several key components that work together within the Hono API server. An incoming request to an auth endpoint is first handled by the better-auth middleware. This middleware uses a Drizzle adapter to communicate with the database for operations like creating users or verifying credentials. The API routes and data schemas are defined in a shared contract package, which is used by both the server for implementation and the client for type-safe consumption.

The diagram below illustrates the interaction between these core components.

This diagram shows the flow of an authentication request through the Hono server, better-auth library, and Drizzle adapter to the database.
Sources: apps/api/src/index.ts:9, apps/api/src/lib/auth.ts:6-18, README.md

Core Components

better-auth Configuration

The core of the authentication logic is configured in apps/api/src/lib/auth.ts. The project utilizes better-auth with the drizzleAdapter to connect to the database.

Key configuration points include:

• Email & Password Strategy: Enabled for standard credential-based login.
• Drizzle Adapter: Connects better-auth to the Drizzle ORM, specifying the PostgreSQL provider (pg) and the database schema tables for users, sessions, accounts, and verifications.
• OpenAPI Plugin: Integrates better-auth with OpenAPI for automatic documentation generation.

// Source: apps/api/src/lib/auth.ts:6-18
export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
  },
  plugins: [openAPI()],
  database: drizzleAdapter(db, {
    provider: "pg",
    schema: {
      user: schema.user,
      session: schema.session,
      account: schema.account,
      verification: schema.verification,
    },
  }),
});

Database Schema

The drizzleAdapter configuration implies a specific database structure for authentication. The following tables are required by better-auth: user, session, account, and verification.

The relationship between these entities is visualized in the ER diagram below.

This diagram shows the database tables required by the better-auth Drizzle adapter.
Sources: apps/api/src/lib/auth.ts:13-17

API Contract

The authentication endpoints are formally defined in the @contract-based-monorepo/contract package. This ensures that any client or server implementation adheres to the same set of routes, methods, and data schemas. The oc.route helper from @orpc/contract is used to define each endpoint.

The main contract object exports all auth routes under the auth key.

// Source: packages/contract/src/contract/index.ts:4-8
export const contract = {
  auth: {
    signup,
    signin,
    me,
  },
  // ... other contracts
};

Routing and Middleware

In the main API entry point, apps/api/src/index.ts, the Hono server is configured to route authentication-related requests and apply necessary middleware.

1. handleBetterAuth: All requests to /api/auth/* are passed to the better-auth handler.
2. handleAuthContext: A subsequent middleware that likely extracts session/user information from the request and places it in the Hono context for downstream handlers.
3. Context Propagation: The authenticated user and session are then passed into the context for ORPC and OpenAPI handlers.

The following diagram shows the request flow through the Hono middleware stack.

API Endpoints

The authentication API exposes three primary endpoints defined in the contract.

Method	Path	Summary	Input Schema	Output Schema	Source File
POST	/auth/signup	Sign up a new user	NewUserSchema	UserSchema	packages/contract/src/contract/auth.ts:5-11
POST	/auth/signin	Sign in a user	CredentialSchema	TokenSchema	packages/contract/src/contract/auth.ts:13-19
GET	/auth/me	Get the current user	(None)	UserSchema	packages/contract/src/contract/auth.ts:21-26

Sign-in Flow

The following sequence diagram illustrates the process of a user signing in.

This diagram shows the interactions between the client, server, and database during a sign-in request.
Sources: packages/contract/src/contract/auth.ts:13-19, apps/api/src/lib/auth.ts:11-18

API Documentation

The authentication system is documented using OpenAPI. The configuration in apps/api/src/handlers/openapi.ts defines a bearerAuth security scheme, indicating that protected endpoints require a bearer token. The interactive Scalar documentation is available at the /api/docs endpoint.

// Source: apps/api/src/handlers/openapi.ts:16-24
    security: [{ bearerAuth: [] }],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: "http",
          scheme: "bearer",
        },
      },
    },

This configuration ensures that endpoints like /auth/me are properly marked as secured in the generated API documentation.
Sources: apps/api/src/handlers/openapi.ts:16-24, apps/api/src/index.ts:11