Agentuity Auth - First-Class BetterAuth Integration

[rblalock]

PR: Agentuity Auth - First-Class BetterAuth Integration

What This Is

A first-class auth service for developers building apps on Agentuity. Uses BetterAuth as the foundation with zero-config defaults.

• Auth for dev users, not Agentuity's identity system
• Tables live in dev Postgres databases
• Thin wrapper over BetterAuth - fully customizable

---

Developer Experience

When adding Agentuity Authentication support (via CLI project create auth init for existing projects or create for new projects), some of the things below will auto get setup, run a sql script to populate your agentuity postgres db, etc.

View migration.ts for the tables that get setup.

1. auth.ts

import { Pool } from 'pg';
import {
	createAgentuityAuth,
	createSessionMiddleware,
	createApiKeyMiddleware,
} from '@agentuity/auth/agentuity';

const pool = new Pool({ connectionString: process.env.DATABASE_URL! });

export const auth = createAgentuityAuth({
	database: pool,
	basePath: '/api/auth',
	secret: process.env.BETTER_AUTH_SECRET!,
	emailAndPassword: {
		enabled: true,
	},
});

// Required auth middleware - returns 401 if not authenticated
export const authMiddleware = createSessionMiddleware(auth);

// API key middleware for programmatic access routes
export const apiKeyMiddleware = createApiKeyMiddleware(auth);

// Type export for end-to-end type safety (maybe we need to do this internally in the package now that i think about it)
export type Auth = typeof auth;

2. Add Routes

// Mount BetterAuth routes (sign-in, sign-up, sign-out, session, token, etc.)
// See mountBetterAuthRoutes ts docs for why this wrapper is required
api.on(['GET', 'POST'], '/auth/*', mountBetterAuthRoutes(auth));

3. Protect API Routes

// Session-based auth (cookies/bearer tokens)
api.get('/me', authMiddleware, async (c) => {
	const user = await c.var.auth.getUser();
	return c.json({ id: user.id, name: user.name });
});

// Org role-based access
api.get('/admin', authMiddleware, async (c) => {
	const hasAdminRole = await c.var.auth.hasOrgRole('owner', 'admin');
	const org = await c.var.auth.getOrg();
	
       return c.json({ role: org?.role });
});

// API key-protected routes
api.post('/projects', apiKeyMiddleware, async (c) => {
	const canWriteProject = c.var.auth.hasPermission('project', 'write');
	return c.json({ success: true });
});

4. Agents can access a user's data too (even through agent to agent comms)

Discussion point: put this in the core agent context instead of needing to wrap it.

import { withSession } from '@agentuity/auth/agentuity';

export default createAgent('my-agent', {
	handler: withSession(async (ctx, { auth, org }, input) => {
		// auth.user, auth.session available
		return { userId: auth.user.id };
	}),
});

Middleware

Middleware	Purpose	Header
createSessionMiddleware(auth, opts)	Session/bearer auth	Cookies, Authorization: Bearer
createApiKeyMiddleware(auth, opts)	API key only	x-agentuity-auth-api-key

app.use('/api/*', createSessionMiddleware(authClient));
app.use('/api/*', createApiKeyMiddleware(auth));

5. React Client

// src/web/auth-client.ts
import { createAuthClient } from 'better-auth/react';

// Auth client has useful hooks, etc.
export const { useSession, signIn, signUp, signOut } = createAuthClient();

// src/web/App.tsx
import { AgentuityBetterAuth } from '@agentuity/auth/agentuity/client';

function App() {
	return (
		<AgentuityProvider>
			<AgentuityBetterAuth authClient={authClient}>
				{/* Auth header automatically injected into API calls */}
			</AgentuityBetterAuth>
		</AgentuityProvider>
	);
}

Auth Helpers on c.var.auth

Org Helpers

• org - Minimal org data (just { id }) from session
• getOrg() - Fetches full org (name, slug, role) lazily, caches result
• getOrgRole() - Returns current user's role in active org
• hasOrgRole(...roles) - Check if user has one of the specified roles

API Key Helpers

• authMethod - 'session' | 'api-key' | 'bearer'
• apiKey - API key context with id, name, permissions
• hasPermission(resource, ...actions) - Check if API key has required permissions

---

What's Included

Default Plugins (enabled automatically)

Plugin	Purpose
organization	Multi-tenancy, teams
bearer	Accept Authorization header
jwt	Token signing/verification
apiKey	Programmatic API access

Auth Methods

Both produce the same c.var.auth context:

• Session - Cookie-based, default for browsers
• API Key - Header-based (x-agentuity-auth-api-key), for programmatic access

---

CLI Integration

New Project

If yes: provisions DB, installs deps, generates auth.ts, runs migrations, prints wiring examples.

Skipped automatically for clerk and auth0 templates.

Existing Project

agentuity project auth init

Walks through: database selection → dependency install → auth.ts generation → migrations → integration examples.

---

Database

Auth tables created automatically via ensureAuthSchema() (called by createAgentuityAuth):

• user, session, account, verification (BetterAuth core)
• organization, member, invitation (org plugin)
• jwks (JWT plugin)
• apiKey (API key plugin)

---

Package Exports

# Server
@agentuity/auth/agentuity 
createAgentuityAuth, createSessionMiddleware, createApiKeyMiddleware, withSession, mountBetterAuthRoutes

# Browser
@agentuity/auth/agentuity/client  AgentuityBetterAuth component, etc

Peer dependency: better-auth (only needed if using Agentuity Auth, not Clerk/Auth0)

---

New Template

etc

---

Test App

See apps/testing/ag-auth-test-app/ for a complete working example.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch first-class-auth

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}