Agentuity Documentation

Choose the auth path based on who owns identity. For new apps that should let users sign in with their Agentuity account, start with Sign in with Agentuity. Use @agentuity/auth when you need app-owned sessions, API keys, or bearer tokens.

Which Auth Path Should I Use?

Need	Use	Start Here
Users sign in with their Agentuity account	Agentuity OIDC provider	Sign in with Agentuity
Users grant scoped access to Agentuity resources	Agentuity OIDC provider and OAuth scopes	Sign in with Agentuity
Your app owns users, sessions, API keys, or bearer tokens	`@agentuity/auth`	Quick Start
Manage OAuth app credentials and scopes	CLI or REST API	CLI OAuth commands

Quick Start with `@agentuity/auth`

Install the auth and drizzle packages:

bun add @agentuity/auth @agentuity/drizzle

Create an auth instance, mount the auth routes, and protect your API with session middleware:

typescriptsrc/api/index.ts

import { Hono } from 'hono';
import type { Env } from '@agentuity/runtime';
import { createAuth, mountAuthRoutes, createSessionMiddleware } from '@agentuity/auth';
 
const auth = createAuth({
  connectionString: process.env.DATABASE_URL,
});
 
const router = new Hono<Env>();
 
// Expose sign-in, sign-up, session, and token endpoints
router.on(['GET', 'POST'], '/api/auth/*', mountAuthRoutes(auth));
 
// Require a valid session for all other API routes
router.use('/api/*', createSessionMiddleware(auth));
 
export default router;

Auth Methods

Method	When to Use	How It Works
Session	Browser users with a login flow	Cookie-based, managed by BetterAuth
API Key	Server-to-server or CLI tools	Header: `x-agentuity-auth-api-key` or `Authorization: ApiKey <key>`
Bearer Token	JWT-based service auth	Header: `Authorization: Bearer <token>`

You can check which method authenticated a request with ctx.auth.authMethod, which returns 'session', 'api-key', or 'bearer'.

Auth in Different Contexts

Let users authenticate with Agentuity and grant scoped access

React Frontend

AuthProvider, useAuth hooks, and login forms for browser apps

Agent Handlers

Full ctx.auth reference with method signatures and return types

CLI OAuth

Create and manage OAuth/OIDC applications from the command line

Default Plugins

Agentuity Auth includes four plugins automatically:

Plugin	Purpose
`organization`	Multi-tenancy with teams, roles, and invitations
`jwt`	JWT token generation with a JWKS endpoint
`bearer`	Bearer token auth via the `Authorization` header
`apiKey`	API key authentication for programmatic access

Full Control Over Plugins

Pass skipDefaultPlugins: true to createAuth() and add only the plugins you need. This is useful when you want a minimal setup or need to customize plugin options.

Database Setup

Agentuity Auth needs a PostgreSQL database to store users, sessions, and keys.

Connection string (simplest). Provide a URL and Agentuity creates the Drizzle adapter with the default resilient Postgres pool:

import { createAuth } from '@agentuity/auth';
 
const auth = createAuth({
  connectionString: process.env.DATABASE_URL,
});

Bring your own adapter. If you already have a Drizzle setup, pass it directly:

import { createAuth } from '@agentuity/auth';
import { createPostgresDrizzle, drizzleAdapter } from '@agentuity/drizzle';
import * as authSchema from '@agentuity/auth/schema';
import * as appSchema from './schema';
 
function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`${name} is required`);
  }
  return value;
}
 
const schema = { ...authSchema, ...appSchema };
const { db } = createPostgresDrizzle({
  connectionString: requireEnv('DATABASE_URL'),
  schema,
});
 
const auth = createAuth({
  database: drizzleAdapter(db, { provider: 'pg', schema: authSchema }),
});

Schema Exports

The @agentuity/auth/schema export provides all auth-related Drizzle tables: user, session, account, verification, organization, member, invitation, and apiKey.

Environment Variables

Variable	Description	Default
`DATABASE_URL`	PostgreSQL connection string	Required
`AGENTUITY_AUTH_SECRET`	Secret for signing tokens	Falls back to `BETTER_AUTH_SECRET`
`AGENTUITY_CLOUD_BASE_URL`	Platform-provided base URL for auth callbacks	Checked before `AGENTUITY_BASE_URL`
`AGENTUITY_BASE_URL`	Base URL for auth callbacks	Checked before `BETTER_AUTH_URL`

By default, trusted origins include the resolved base URL, the incoming request origin, AGENTUITY_CLOUD_DOMAINS, and AUTH_TRUSTED_DOMAINS. AGENTUITY_BASE_URL is also trusted when set, even if AGENTUITY_CLOUD_BASE_URL supplied the resolved base URL. Passing trustedOrigins to createAuth() replaces that default list.

Replace Dev Secrets Before Deploying

Generate a secure secret with openssl rand -hex 32 and store it in your environment variables before deploying.

Use the Agentuity OIDC provider when your app should redirect users to Agentuity, receive an authorization code, and create its own local app session from the returned profile. The provider handles identity, consent, OAuth apps, scopes, and tokens.

See Sign in with Agentuity for the route example, token storage pattern, and OAuth app setup.

Next Steps

Sign in with Agentuity: Add Agentuity account sign-in and scoped access
React Frontend Auth: AuthProvider setup, useAuth hooks, and sign-in/sign-up forms
ctx.auth Reference: Complete method signatures and return types
CLI OAuth Commands: Create and manage OAuth/OIDC applications