Website Quickstart

Integrate Auth Agent into your website to allow AI agent authentication

For Website Developers

This guide shows you how to integrate Auth Agent into your website to allow AI agents to authenticate.

Step 1: Register OAuth Client

Before integrating, you need credentials:

1. Navigate to Website Console

   Go to auth-agent.com/console/website

2. Register New Client

   Click “Register New Client” and provide:

   • Client name (e.g., “My Website”)
   • Redirect URIs (e.g., https://example.com/api/auth/callback/auth-agent)
3. Copy Credentials

   Save your client_id and client_secret to your environment variables

---

Step 2: Choose Your Integration Method

Better Auth (Recommended)

If you use Better Auth, integration takes 2 minutes.

Install the Plugin

npm install auth-agent-better-auth

Add to Your Auth Config

// lib/auth.ts
import { betterAuth } from "better-auth";
import { authAgent } from "auth-agent-better-auth/server";

export const auth = betterAuth({
  database: /* your database */,
  plugins: [
    authAgent({
      clientId: process.env.AUTH_AGENT_CLIENT_ID!,
      clientSecret: process.env.AUTH_AGENT_CLIENT_SECRET!,
      scenario: "fullAccount", // or "contextualProfile" or "freshProfile"
    })
  ]
});

Add the Button

// app/login/page.tsx
import { AuthAgentButton } from "auth-agent-better-auth/components";

export default function LoginPage() {
  return (
    <div>
      <h1>Sign In</h1>
      <AuthAgentButton callbackURL="/dashboard" />
    </div>
  );
}

That’s It

The plugin handles:

• OAuth 2.1 authorization flow
• PKCE challenge generation
• Token exchange
• Session creation
• All three integration scenarios

npm: auth-agent-better-auth

View package documentation

Manual Integration

For custom auth systems or frameworks without Better Auth support.

Overview

When an AI agent wants to access your website:

1. The agent navigates to your sign-in page
2. Clicks “Sign in with Auth Agent”
3. You redirect to Auth Agent’s authorization page
4. The agent authenticates (handled automatically)
5. Auth Agent redirects back with an authorization code
6. You exchange the code for tokens
7. You create a session based on your chosen scenario

Add Sign-In Button

// components/AuthAgentButton.tsx
'use client';

export function AuthAgentButton() {
  const handleSignIn = async () => {
    // Generate PKCE challenge
    const codeVerifier = generateRandomString(128);
    const codeChallenge = await sha256(codeVerifier);
    const state = generateRandomString(32);
    
    // Store for callback
    sessionStorage.setItem('code_verifier', codeVerifier);
    sessionStorage.setItem('oauth_state', state);

    const params = new URLSearchParams({
      client_id: process.env.NEXT_PUBLIC_AUTH_AGENT_CLIENT_ID!,
      redirect_uri: `${window.location.origin}/api/auth/callback`,
      response_type: 'code',
      state,
      code_challenge: codeChallenge,
      code_challenge_method: 'S256',
      scope: 'openid profile email',
    });

    window.location.href = `https://api.auth-agent.com/authorize?${params}`;
  };

  return (
    <button onClick={handleSignIn}>
      Sign in with Auth Agent
    </button>
  );
}

Handle Callback

// app/api/auth/callback/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url);
  const code = searchParams.get('code');
  const state = searchParams.get('state');

  // Validate state (from your session/cookie)
  // Get code_verifier from session

  // Exchange code for tokens
  const tokenResponse = await fetch('https://api.auth-agent.com/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      redirect_uri: `${process.env.NEXT_PUBLIC_BASE_URL}/api/auth/callback`,
      client_id: process.env.AUTH_AGENT_CLIENT_ID!,
      client_secret: process.env.AUTH_AGENT_CLIENT_SECRET!,
      code_verifier: codeVerifier,
    }),
  });

  const tokens = await tokenResponse.json();

  // Get user info
  const userResponse = await fetch('https://api.auth-agent.com/userinfo', {
    headers: { Authorization: `Bearer ${tokens.access_token}` },
  });
  const userInfo = await userResponse.json();

  // Create session based on your scenario
  // userInfo.email - user's email
  // userInfo.sub - agent ID

  return NextResponse.redirect('/dashboard');
}

See the full manual integration examples below for each scenario.

---

Integration Scenarios

Auth Agent supports three patterns for how agents interact with user accounts:

Full Account Access

Agent uses user’s existing account

Contextual Profile

Separate agent profile with user context

Fresh Profile

Independent agent profile

Comparison

Feature	Full Account	Contextual Profile	Fresh Profile
Call /userinfo	Required	Required	Not needed
User Email Access	Yes	Yes	No
Access to User Data	Full	Read-only	None
Agent Attribution	No	Yes	Yes
Privacy Level	Low	Medium	High

---

Scenario 1: Full Account Access

Use when: The agent needs full access to the user’s existing account (e.g., e-commerce, banking).

Better Auth Config

authAgent({
  clientId: process.env.AUTH_AGENT_CLIENT_ID!,
  clientSecret: process.env.AUTH_AGENT_CLIENT_SECRET!,
  scenario: "fullAccount",
})

Manual Implementation

// In your callback handler
const userInfo = await fetch('https://api.auth-agent.com/userinfo', {
  headers: { Authorization: `Bearer ${tokens.access_token}` },
}).then(r => r.json());

// Find existing user by email
const user = await db.users.findOne({ email: userInfo.email });

if (!user) {
  return NextResponse.redirect('/auth/register');
}

// Create session for existing user
await createSession({ userId: user.id, agentId: userInfo.sub });

---

Scenario 2: Contextual Profile

Use when: You want separate agent profiles but need access to user context (e.g., social media, content platforms).

Better Auth Config

authAgent({
  clientId: process.env.AUTH_AGENT_CLIENT_ID!,
  clientSecret: process.env.AUTH_AGENT_CLIENT_SECRET!,
  scenario: "contextualProfile",
})

Manual Implementation

// In your callback handler
const userInfo = await fetch('https://api.auth-agent.com/userinfo', {
  headers: { Authorization: `Bearer ${tokens.access_token}` },
}).then(r => r.json());

// Find or create user
const user = await db.users.findOrCreate({ email: userInfo.email });

// Create agent profile linked to user
const agentProfile = await db.agentProfiles.create({
  agentId: userInfo.sub,
  linkedUserId: user.id,
});

// Agent can read user data but actions are attributed to agent
await createSession({ 
  agentProfileId: agentProfile.id, 
  linkedUserId: user.id 
});

---

Scenario 3: Fresh Profile

Use when: You want completely independent agent profiles with no user context (e.g., privacy-focused services).

Better Auth Config

authAgent({
  clientId: process.env.AUTH_AGENT_CLIENT_ID!,
  clientSecret: process.env.AUTH_AGENT_CLIENT_SECRET!,
  scenario: "freshProfile",
})

Manual Implementation

// In your callback handler
// DO NOT call /userinfo - extract agent ID from JWT instead
const decoded = jwt.decode(tokens.access_token);
const agentId = decoded.sub;

// Create fresh agent profile (no user linkage)
const agentProfile = await db.agentProfiles.create({
  agentId,
  // No linkedUserId - completely independent
});

await createSession({ agentProfileId: agentProfile.id });

---

Decision Guide

1. Does the agent need to act on the user's behalf?

   Yes → Full Account Access

   No → Continue

2. Does the agent need user context or preferences?

   Yes → Contextual Profile

   No → Fresh Profile

---

Next Steps

Integration Scenarios

Detailed guide with diagrams

API Reference

Complete endpoint documentation

Security Best Practices

Secure your integration

GitHub Examples

View example implementations