Integration Scenarios

Overview

Auth Agent supports three distinct integration patterns, allowing websites to choose how they handle AI agent authentication based on their specific requirements and user expectations.

The Three Scenarios

Full Account Access

Agent operates within the user’s existing account

Contextual Profile

Separate agent profile with access to user context

Fresh Profile

Independent agent profile with no user data

Scenario 1: Full Account Access

The agent operates directly within the user’s existing account with complete access to their data and preferences.

When to Use

E-commerce sites where agents need to access order history and saved items
Banking apps where agents manage the user’s actual accounts
Email clients where agents read and send from the user’s inbox
Any service where the agent is acting on behalf of the user

Implementation

Exchange Authorization Code

After receiving the authorization code, exchange it for access tokens

Get User Email

Call /userinfo to get the user’s email address

Link to Existing Account

Find the user’s existing account by email and create a session

Grant Full Access

The agent now has complete access to the user’s account

Code Example

// After OAuth callback with authorization code
async function handleFullAccountAccess(code: string, codeVerifier: string) {
  // Exchange code for tokens
  const tokens = await exchangeCodeForTokens(code, codeVerifier);

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

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

  if (!existingUser) {
    throw new Error('User account not found');
  }

  // Create session with full account access
  const session = await createSession({
    userId: existingUser.id,
    type: 'agent',
    agentId: userInfo.sub,
    accessToken: tokens.access_token,
    refreshToken: tokens.refresh_token,
  });

  return { sessionId: session.id, user: existingUser };
}

Flow Diagram

Pros & Cons

Advantages

Seamless experience for users
Agent has access to all user data and history
Simpler implementation
No data duplication

Disadvantages

Agent actions appear as user actions
Harder to distinguish agent vs user activity
Higher security risk if agent is compromised
May not comply with some regulatory requirements

Scenario 2: Contextual Profile

Create a separate agent profile but provide access to the user’s context and data.

When to Use

Social media where you want separate agent activity but need access to user’s network
Content platforms where agents create content under their own identity but can access user preferences
Collaboration tools where agent actions should be clearly attributed but need user context
Services that need to audit agent vs user actions separately

Implementation

Exchange Authorization Code

After receiving the authorization code, exchange it for access tokens

Get User Email

Call /userinfo to get the user’s email address

Create Agent Profile

Create a new agent profile linked to the user’s account

Grant Contextual Access

Agent can access user data but actions are attributed to the agent

Code Example

async function handleContextualProfile(code: string, codeVerifier: string) {
  // Exchange code for tokens
  const tokens = await exchangeCodeForTokens(code, codeVerifier);

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

  // Find or create user by email
  // Note: Only email is provided, not name
  const user = await db.users.findOrCreate({
    where: { email: userInfo.email },
    defaults: { name: null }, // Name not provided by Auth Agent
  });

  // Create agent profile linked to user
  // Note: Only email is provided, not name
  const agentProfile = await db.agentProfiles.create({
    agentId: userInfo.sub,
    linkedUserId: user.id,
    name: `Agent ${userInfo.sub.slice(-6)}`, // Use agent ID since name not provided
    model: extractModelFromToken(tokens.access_token),
  });

  // Create session for agent profile
  const session = await createSession({
    agentProfileId: agentProfile.id,
    linkedUserId: user.id,  // Link for context access
    type: 'agent_contextual',
    accessToken: tokens.access_token,
    refreshToken: tokens.refresh_token,
  });

  return { sessionId: session.id, agentProfile, linkedUser: user };
}

Access Control Example

// Middleware to handle contextual access
function requireContextualAccess(req, res, next) {
  const session = req.session;

  if (session.type !== 'agent_contextual') {
    return res.status(403).json({ error: 'Invalid session type' });
  }

  // Agent can read user data
  req.canReadUserData = true;

  // But writes are attributed to agent
  req.actorId = session.agentProfileId;
  req.actorType = 'agent';

  next();
}

// Example usage
app.post('/api/posts', requireContextualAccess, async (req, res) => {
  const { linkedUserId, agentProfileId } = req.session;

  // Agent can read user's preferences
  const userPrefs = await db.preferences.findOne({
    where: { userId: linkedUserId }
  });

  // But post is created by the agent
  const post = await db.posts.create({
    content: req.body.content,
    authorId: agentProfileId,
    authorType: 'agent',
    // Can use user preferences
    visibility: userPrefs.defaultVisibility,
  });

  res.json(post);
});

Flow Diagram

Pros & Cons

Advantages

Clear attribution of agent actions
Agent has access to user context
Better audit trail
Balanced security model
Can implement fine-grained access control

Disadvantages

More complex implementation
Need to manage agent profiles separately
Must define access control rules
Potential for confusion about what agent can access

Scenario 3: Fresh Profile

Create a completely independent agent profile with no access to user context or data.

When to Use

Services where privacy is paramount
Platforms where agent and user identities should be completely separate
Testing environments
Services that don’t require user context
Compliance with strict data separation requirements

Implementation

Exchange Authorization Code

After receiving the authorization code, exchange it for access tokens

Skip /userinfo Call

Do NOT call /userinfo - no need for user email

Extract Agent ID

Get agent ID from the access token JWT

Create Fresh Profile

Create a new, independent agent profile

Code Example

async function handleFreshProfile(code: string, codeVerifier: string) {
  // Exchange code for tokens
  const tokens = await exchangeCodeForTokens(code, codeVerifier);

  // DO NOT call /userinfo - we don't need user email

  // Extract agent ID from JWT
  const decoded = jwt.decode(tokens.access_token);
  const agentId = decoded.sub;
  const model = decoded.model;

  // Create fresh agent profile (no user linkage)
  const agentProfile = await db.agentProfiles.create({
    agentId: agentId,
    model: model,
    name: `Agent ${agentId.slice(-6)}`,
    // No linkedUserId - completely independent
  });

  // Create session for agent profile
  const session = await createSession({
    agentProfileId: agentProfile.id,
    type: 'agent_fresh',
    accessToken: tokens.access_token,
    refreshToken: tokens.refresh_token,
  });

  return { sessionId: session.id, agentProfile };
}

Flow Diagram

Pros & Cons

Advantages

Maximum privacy
Clear separation of identities
Simpler permission model
No risk of accessing user data
Better for compliance

Disadvantages

Agent cannot access user preferences
No personalization
May require agent to ask for information the user already provided
Less seamless user experience

Comparison Table

Feature	Full Account	Contextual Profile	Fresh Profile
User Email Access	✅ Yes	✅ Yes	❌ No
Access to User Data	✅ Full	⚠️ Read-only	❌ None
Agent Attribution	❌ No	✅ Yes	✅ Yes
Privacy Level	⚠️ Low	⚠️ Medium	✅ High
Implementation Complexity	🟢 Simple	🟡 Medium	🟢 Simple
Use `/userinfo`	✅ Required	✅ Required	❌ Not needed
Personalization	✅ Full	⚠️ Partial	❌ None

Decision Guide

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

Yes → Full Account Access (Scenario 1)No → Continue to next question

Does the agent need user context or preferences?

Yes → Contextual Profile (Scenario 2)No → Fresh Profile (Scenario 3)

Are there strict privacy or compliance requirements?

Yes → Consider Fresh Profile (Scenario 3) or implement strict access controls in Contextual Profile (Scenario 2)No → Choose based on user experience needs

Implementation Checklist

Full Account
Contextual Profile
Fresh Profile

Implement OAuth flow with email scope
Call /userinfo endpoint after token exchange
Find existing user by email
Handle case where user doesn’t exist
Create session with full account access
Implement logout with token revocation
Add agent identification in activity logs

Best Practices

Communicate Clearly

Make it clear to users which scenario you’re implementing. Show them what data the agent can access during the authorization flow.

Implement Revocation

Allow users to revoke agent access at any time through your settings page. Call the /revoke endpoint to invalidate tokens.

Audit Logs

Keep detailed logs of agent actions, especially for Scenario 1 (Full Account Access) where agent actions appear as user actions.

Rate Limiting

Implement rate limiting for agent requests, as agents may make more requests than typical users.

Security Monitoring

Monitor for unusual patterns that might indicate a compromised agent or unauthorized access.

Next Steps

Quickstart Guide

Implement your chosen scenario

API Reference

Detailed endpoint documentation

Security Best Practices

Secure your integration

Code Examples

Real-world implementation examples

Getting Started

Guides

Integration Guides

Security & Advanced

API Reference

OAuth Endpoints

Agent Back-Channel

Discovery

​Overview

​The Three Scenarios

Full Account Access

Contextual Profile

Fresh Profile

​Scenario 1: Full Account Access

​When to Use

​Implementation

​Code Example

​Flow Diagram

​Pros & Cons

​Scenario 2: Contextual Profile

​When to Use

​Implementation

​Code Example

​Access Control Example

​Flow Diagram

​Pros & Cons

​Scenario 3: Fresh Profile

​When to Use

​Implementation

​Code Example

​Flow Diagram

​Pros & Cons

​Comparison Table

​Decision Guide

​Implementation Checklist

​Best Practices

​Next Steps

Quickstart Guide

API Reference

Security Best Practices

Code Examples

Overview

The Three Scenarios

Scenario 1: Full Account Access

When to Use

Implementation

Code Example

Flow Diagram

Pros & Cons

Scenario 2: Contextual Profile

When to Use

Implementation

Code Example

Access Control Example

Flow Diagram

Pros & Cons

Scenario 3: Fresh Profile

When to Use

Implementation

Code Example

Flow Diagram

Pros & Cons

Comparison Table

Decision Guide

Implementation Checklist

Best Practices

Next Steps