Skip to main content

​
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

​
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

FeatureFull AccountContextual ProfileFresh Profile
Call /userinfoRequiredRequiredNot needed
User Email AccessYesYesNo
Access to User DataFullRead-onlyNone
Agent AttributionNoYesYes
Privacy LevelLowMediumHigh

​
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 AccessNo → Continue
2

Does the agent need user context or preferences?

Yes → Contextual ProfileNo → 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