Authentication Management

Overview

Session snapshots preserve authentication state, allowing you to maintain logged-in sessions across multiple agent sessions without re-authenticating.

How Authentication is Preserved

Authentication state is preserved through snapshots in several ways:

Browser Cookies

All cookies stored in browser profile
Preserved in filesystem snapshots

Web Storage

localStorage and sessionStorage
Preserved in browser profile

Browser State

Logged-in sessions
Authentication tokens
Session data

When you save a filesystem snapshot, all browser state including cookies, localStorage, sessionStorage, and authentication tokens are captured and can be restored in future sessions.

Best Practices

1. Use Filesystem Snapshots

For authentication-critical applications, always use save_snapshot_mode=filesystem:

JavaScript
Python
HTTPie

// ✅ Correct: Use filesystem for authentication
await fetch(`https://api.agi.tech/v1/sessions/${sessionId}?save_snapshot_mode=filesystem&save_as_default=true`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

// ❌ Incorrect: Memory snapshots may not preserve all auth state
// await fetch(`https://api.agi.tech/v1/sessions/${sessionId}?save_snapshot_mode=memory&save_as_default=true`, {
//   method: 'DELETE',
//   headers: { 'Authorization': `Bearer ${apiKey}` }
// });

# ✅ Correct: Use filesystem for authentication
requests.delete(
    f"https://api.agi.tech/v1/sessions/{session_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    params={
        "save_snapshot_mode": "filesystem",
        "save_as_default": "true"
    }
)

# ❌ Incorrect: Memory snapshots may not preserve all auth state
# requests.delete(
#     f"https://api.agi.tech/v1/sessions/{session_id}",
#     headers={"Authorization": f"Bearer {api_key}"},
#     params={"save_snapshot_mode": "memory", "save_as_default": "true"}
# )

# ✅ Correct: Use filesystem for authentication
http DELETE "https://api.agi.tech/v1/sessions/$SESSION_ID?save_snapshot_mode=filesystem&save_as_default=true" \
  Authorization:"Bearer $AGI_API_KEY"

# ❌ Incorrect: Memory snapshots may not preserve all auth state
# http DELETE "https://api.agi.tech/v1/sessions/$SESSION_ID?save_snapshot_mode=memory&save_as_default=true" \
#   Authorization:"Bearer $AGI_API_KEY"

Save snapshots immediately after successful authentication:

JavaScript
Python
HTTPie

// After logging in and completing authentication
await fetch(`https://api.agi.tech/v1/sessions/${sessionId}?save_snapshot_mode=filesystem&save_as_default=true`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

# After logging in and completing authentication
requests.delete(
    f"https://api.agi.tech/v1/sessions/{session_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    params={
        "save_snapshot_mode": "filesystem",
        "save_as_default": "true"
    }
)

# After logging in and completing authentication
http DELETE "https://api.agi.tech/v1/sessions/$SESSION_ID?save_snapshot_mode=filesystem&save_as_default=true" \
  Authorization:"Bearer $AGI_API_KEY"

3. Update Regularly

Refresh snapshots periodically to update authentication tokens before they expire:

JavaScript
Python
HTTPie

// Check if authentication is still valid
const result = await session.runTask("Check if I'm logged in");

if (result.toLowerCase().includes("not logged in")) {
  // Re-authenticate and save new snapshot
  await session.runTask("Login again");
  
  // Save updated snapshot
  await fetch(`https://api.agi.tech/v1/sessions/${sessionId}?save_snapshot_mode=filesystem&save_as_default=true`, {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });
}

# Check if authentication is still valid
result = session.run_task("Check if I'm logged in")

if "not logged in" in result.lower():
    # Re-authenticate and save new snapshot
    session.run_task("Login again")
    
    # Save updated snapshot
    requests.delete(
        f"https://api.agi.tech/v1/sessions/{session_id}",
        headers={"Authorization": f"Bearer {api_key}"},
        params={
            "save_snapshot_mode": "filesystem",
            "save_as_default": "true"
        }
    )

# Check authentication status
RESULT=$(http POST https://api.agi.tech/v1/sessions/$SESSION_ID/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Check if I'm logged in" | jq -r '.content')

if echo "$RESULT" | grep -qi "not logged in"; then
  # Re-authenticate
  http POST https://api.agi.tech/v1/sessions/$SESSION_ID/message \
    Authorization:"Bearer $AGI_API_KEY" \
    message="Login again"
  
  # Save updated snapshot
  http DELETE "https://api.agi.tech/v1/sessions/$SESSION_ID?save_snapshot_mode=filesystem&save_as_default=true" \
    Authorization:"Bearer $AGI_API_KEY"
fi

4. Multiple Environments

Maintain separate environments for different authentication contexts:

JavaScript
Python
HTTPie

// Work account
await fetch(`https://api.agi.tech/v1/sessions/${workSessionId}?save_snapshot_mode=filesystem&save_as_default=true`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

// Personal account (use different user_id)
await fetch(`https://api.agi.tech/v1/sessions/${personalSessionId}?save_snapshot_mode=filesystem&save_as_default=true`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

# Work account
requests.delete(
    f"https://api.agi.tech/v1/sessions/{work_session_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    params={
        "save_snapshot_mode": "filesystem",
        "save_as_default": "true"
    }
)

# Personal account (use different user_id)
requests.delete(
    f"https://api.agi.tech/v1/sessions/{personal_session_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    params={
        "save_snapshot_mode": "filesystem",
        "save_as_default": "true"
    }
)

# Work account
http DELETE "https://api.agi.tech/v1/sessions/$WORK_SESSION_ID?save_snapshot_mode=filesystem&save_as_default=true" \
  Authorization:"Bearer $AGI_API_KEY"

# Personal account (use different user_id)
http DELETE "https://api.agi.tech/v1/sessions/$PERSONAL_SESSION_ID?save_snapshot_mode=filesystem&save_as_default=true" \
  Authorization:"Bearer $AGI_API_KEY"

Authentication State Lifecycle

Create Session → Fresh environment (no auth)
Login to Service → Authentication cookies stored
Delete Session with Snapshot → Auth state saved
Create New Session from Snapshot → Auth state restored
Continue Using Service → Already authenticated

Troubleshooting

Authentication Not Preserved

If authentication is not preserved, check these common issues:

Check Snapshot Mode

Ensure you’re using filesystem mode, not memory or none:

Verify

# Check your delete request includes filesystem mode
http DELETE "https://api.agi.tech/v1/sessions/$SESSION_ID?save_snapshot_mode=filesystem&save_as_default=true" \
  Authorization:"Bearer $AGI_API_KEY"

Verify Default Environment

Confirm the environment is set as default:

Verify

# When creating session, ensure you're restoring from default
http POST https://api.agi.tech/v1/sessions \
  Authorization:"Bearer $AGI_API_KEY" \
  agent_name=agi-0 \
  restore_default_environment_from_user_id=$USER_ID

Token Expiration

Some authentication tokens expire. You may need to re-authenticate periodically:

Check & Refresh

// Check if authentication is still valid
const result = await session.runTask("Check if I'm logged in");

if (result.toLowerCase().includes("not logged in")) {
  // Re-authenticate and save new snapshot
  await session.runTask("Login again");
}

Cookie Domain

Complete Example

Complete workflow for authentication management:

JavaScript
Python
HTTPie

class AuthManager {
  constructor(apiKey, baseUrl, userId) {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
    this.userId = userId;
  }

  async createSession(restoreFromDefault = true) {
    const payload = { agent_name: "agi-0" };
    
    if (restoreFromDefault) {
      payload.restore_default_environment_from_user_id = this.userId;
    }

    const response = await fetch(`${this.baseUrl}/v1/sessions`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${this.apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    });

    if (!response.ok) {
      throw new Error(`Failed to create session: ${response.statusText}`);
    }

    return await response.json();
  }

  async saveSessionAsDefault(sessionId, snapshotMode = "filesystem") {
    const url = new URL(`${this.baseUrl}/v1/sessions/${sessionId}`);
    url.searchParams.set("save_snapshot_mode", snapshotMode);
    url.searchParams.set("save_as_default", "true");

    const response = await fetch(url.toString(), {
      method: "DELETE",
      headers: {
        "Authorization": `Bearer ${this.apiKey}`,
      },
    });

    if (!response.ok) {
      throw new Error(`Failed to save session: ${response.statusText}`);
    }

    return await response.json();
  }
}

// Usage
const manager = new AuthManager("your-api-key", "https://api.agi.tech", "your-user-id");

// Create session and authenticate
const session = await manager.createSession(false);
const sessionId = session.session_id;

// ... perform authentication ...

// Save as default for future sessions
await manager.saveSessionAsDefault(sessionId, "filesystem");

// Future sessions will automatically restore from default
const newSession = await manager.createSession(true);

import requests

class AuthManager:
    def __init__(self, api_key: str, base_url: str, user_id: str):
        self.api_key = api_key
        self.base_url = base_url
        self.user_id = user_id
        self.headers = {"Authorization": f"Bearer {api_key}"}
    
    def create_session(self, restore_from_default: bool = True):
        payload = {"agent_name": "agi-0"}
        
        if restore_from_default:
            payload["restore_default_environment_from_user_id"] = self.user_id
        
        response = requests.post(
            f"{self.base_url}/v1/sessions",
            headers=self.headers,
            json=payload
        )
        response.raise_for_status()
        return response.json()
    
    def save_session_as_default(self, session_id: str, snapshot_mode: str = "filesystem"):
        response = requests.delete(
            f"{self.base_url}/v1/sessions/{session_id}",
            headers=self.headers,
            params={
                "save_snapshot_mode": snapshot_mode,
                "save_as_default": "true"
            }
        )
        response.raise_for_status()
        return response.json()

# Usage
manager = AuthManager(api_key="your-key", base_url="https://api.agi.tech", user_id="your-user-id")

# Create session and authenticate
session = manager.create_session(restore_from_default=False)
session_id = session["session_id"]

# ... perform authentication ...

# Save as default for future sessions
manager.save_session_as_default(session_id, snapshot_mode="filesystem")

# Future sessions will automatically restore from default
new_session = manager.create_session(restore_from_default=True)

# Create session
SESSION=$(http POST https://api.agi.tech/v1/sessions \
  Authorization:"Bearer $AGI_API_KEY" \
  agent_name=agi-0 | jq -r '.session_id')

# ... perform authentication ...

# Save as default
http DELETE "https://api.agi.tech/v1/sessions/$SESSION?save_snapshot_mode=filesystem&save_as_default=true" \
  Authorization:"Bearer $AGI_API_KEY"

# Future sessions restore from default
NEW_SESSION=$(http POST https://api.agi.tech/v1/sessions \
  Authorization:"Bearer $AGI_API_KEY" \
  agent_name=agi-0 \
  restore_default_environment_from_user_id=$USER_ID | jq -r '.session_id')

Session Snapshots Overview

Back to overview

Saving Snapshots

Learn how to save snapshots

Restoring Snapshots

Learn how to restore from snapshots

Troubleshooting

Fix authentication issues

Getting Started

Use Cases

Best Practices

Advanced

Troubleshooting

Authentication Management

Overview

How Authentication is Preserved

Browser Cookies

Web Storage

Browser State

Best Practices

1. Use Filesystem Snapshots

3. Update Regularly

4. Multiple Environments

Authentication State Lifecycle

Troubleshooting

Authentication Not Preserved

Complete Example

Session Snapshots Overview

Saving Snapshots

Restoring Snapshots

Troubleshooting

Getting Started

Use Cases

Best Practices

Advanced

Troubleshooting

​Overview

​How Authentication is Preserved

Browser Cookies

Web Storage

Browser State

​Best Practices

​1. Use Filesystem Snapshots

​2. Save After Login

​3. Update Regularly

​4. Multiple Environments

​Authentication State Lifecycle

​Troubleshooting

​Authentication Not Preserved

​Complete Example

​Related Guides

Session Snapshots Overview

Saving Snapshots

Restoring Snapshots

Troubleshooting

Overview

How Authentication is Preserved

Best Practices

1. Use Filesystem Snapshots

2. Save After Login

3. Update Regularly

4. Multiple Environments

Authentication State Lifecycle

Troubleshooting

Authentication Not Preserved

Complete Example

Related Guides