Choosing Authentication

In v3, your framework owns the user session. Use Agentuity OIDC when users should sign in with their Agentuity account or grant scoped Agentuity access. Use your framework or auth provider when your app owns users, teams, roles, and sessions.

The v2 @agentuity/auth package is not the primary v3 path. It remains relevant for legacy v2 apps, but new v3 apps should start with one of these shapes:

import { KeyValueClient } from '@agentuity/keyvalue';
 
interface AppUser {
  readonly id: string;
  readonly email: string;
}
 
interface AppSession {
  readonly user: AppUser;
}
 
interface Preferences {
  readonly theme: 'light' | 'dark';
}
 
declare function getSession(request: Request): Promise<AppSession | null>;
 
const kv = new KeyValueClient();
 
export async function getPreferences(request: Request): Promise<Response> {
  const session = await getSession(request);
 
  if (!session) {
    return Response.json({ error: 'Sign in required' }, { status: 401 });
  }
 
  const result = await kv.get<Preferences>('user-preferences', session.user.id);
 
  return Response.json({
    user: session.user,
    preferences: result.exists ? result.data : { theme: 'light' } satisfies Preferences,
  });
}

Keep AGENTUITY_SDK_KEY, OAuth client secrets, and refresh tokens on the server. Browser code should call your framework routes, not Agentuity service APIs directly.

Pick the Auth Path

Framework-Owned Sessions

Most v3 apps should authenticate users before they reach Agentuity service calls:

1. Your auth provider signs the user in.
2. Your framework stores a session cookie or server-side session.
3. Your route handler validates that session.
4. The route handler calls Agentuity service clients with server-only credentials.

That same boundary fits Next.js, React Router, Remix, TanStack Start, Hono, SvelteKit, Nuxt, Astro, and custom backends because Agentuity services do not require a specific auth package in the request path.

Keep the boundary simple: browser code talks to your app routes, and those routes decide which Agentuity services to call. Do not expose AGENTUITY_SDK_KEY, OAuth client secrets, access tokens, or refresh tokens to the browser.

Sign in with Agentuity

Use Agentuity OIDC when Agentuity is the identity provider for the sign-in step, or when your app needs a user's consent to access Agentuity resources.

agentuity cloud oidc create \
  --name "My App" \
  --homepage-url "https://example.com" \
  --type confidential \
  --redirect-uris "https://example.com/auth/callback" \
  --scopes "openid,profile,email"

The callback route still creates your app's local session. Agentuity handles the identity check, consent screen, client credentials, scopes, and token endpoints. Your framework still owns cookies, roles, redirects, and authorization checks inside the app.

If you maintain an older app that still uses @agentuity/auth, treat that package as migration context. New v3 apps should keep browser session state in the framework or auth provider, then call Agentuity services from server routes.

Auth in Different Contexts

Next Steps

• Sign in with Agentuity: add Agentuity account sign-in and scoped access
• Framework-Owned Sessions: wire browser UI to server-owned sessions
• CLI OAuth Commands: create and manage OAuth/OIDC applications
• App Configuration: keep service keys in local and deployed environments
• OAuth API Reference: inspect generated REST details for OAuth apps and consent grants