User Context vs System Context

This chapter explains the two execution contexts in General Bots: User Context and System Context. Understanding these contexts is essential for building secure, properly scoped bot interactions.

Overview

Every API call and BASIC script execution happens in one of two contexts:

User Context

Definition

User Context means the operation is performed as the authenticated user, using their identity and permissions.

Characteristics

• Identity: The logged-in user’s ID
• Permissions: Limited to what the user can access
• Scope: Only user’s own resources
• Token: User’s OAuth access token

When User Context Applies

1. Interactive Chat: User sends a message
2. File Operations: User uploads/downloads files
3. Email Access: User reads their inbox
4. Calendar: User views their schedule
5. Tasks: User manages their task list

Example Flow

User logs in → OAuth token issued → User asks bot to send email
                                           ↓
                               Bot sends email AS the user
                                           ↓
                               Email "From:" shows user's address

BASIC Script Example

' This runs in User Context when triggered by user interaction
' The email is sent from the logged-in user's account

TALK "Who should I email?"
recipient = HEAR

TALK "What's the subject?"
subject = HEAR

TALK "What's the message?"
body = HEAR

SEND MAIL recipient, subject, body
TALK "Email sent from your account to " + recipient

Access Boundaries

In User Context, the bot can only access:

System Context

Definition

System Context means the operation is performed by the bot system itself, using a service account with elevated permissions.

Characteristics

• Identity: Bot’s service account
• Permissions: Defined by admin configuration
• Scope: Cross-user or system-wide resources
• Token: Service account credentials

When System Context Applies

1. Scheduled Tasks: Cron-based script execution via SET SCHEDULE
2. Event Handlers: ON keyword triggers
3. Admin Operations: User management
4. Analytics: Cross-user reporting
5. Backups: System-wide data export
6. Bot-Initiated Messages: Proactive notifications

Example Flow

Schedule triggers at 9:00 AM → System context activated
                                       ↓
                            Bot sends summary to all managers
                                       ↓
                            Email "From:" shows bot's address

BASIC Script Example

' This runs in System Context (scheduled task)
' The bot sends emails from its own account

SET SCHEDULE "0 9 * * 1"  ' Every Monday at 9 AM

' Bot processes data and sends notifications
summary = LLM "Generate weekly summary"
SEND MAIL "team@example.com", "Weekly Summary", summary

PRINT "Weekly summary sent"

Access Boundaries

In System Context, the bot can access:

Determining Context

Automatic Detection

General Bots automatically determines context based on how the script is triggered:

Context in Scripts

The context is determined by the trigger, not by keywords in the script:

' User-triggered script (User Context)
' - Runs when user interacts
' - Uses user's permissions

name = HEAR "What's your name?"
TALK "Hello, " + name

' Scheduled script (System Context)
' - Runs on schedule
' - Uses bot's permissions

SET SCHEDULE "0 8 * * *"  ' Daily at 8 AM
TALK "Good morning! Here's your daily briefing."

Security Implications

User Context Security

System Context Security

Configuration

Service Account Setup

The bot’s system identity is managed through the Directory service (Zitadel). Configure in config.csv:

key,value
system-account-email,bot@yourdomain.com
system-context-permissions,files:read|email:send|calendar:write

Context Restrictions

Limit what System Context can do:

key,value
system-allow-email,true
system-allow-file-delete,false
system-allow-user-create,false
system-allow-config-change,false

Audit Logging

All operations are logged with context:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "context": "user",
  "user_id": "user-123",
  "action": "email:send",
  "resource": "email to client@example.com",
  "result": "success"
}

{
  "timestamp": "2024-01-15T09:00:00Z",
  "context": "system",
  "service_account": "bot-service-account",
  "action": "email:send",
  "resource": "weekly-summary to 47 recipients",
  "trigger": "schedule:weekly-summary",
  "result": "success"
}

Best Practices

Use User Context When

• User initiates the action
• Operation affects only the user
• Audit trail should point to user
• Respecting user permissions is required

Use System Context When

• Scheduled or automated tasks
• Cross-user operations needed
• Bot needs elevated permissions
• System-wide actions required

Security Guidelines

1. Minimize System Context: Use only when necessary
2. Audit Everything: Log all system context operations
3. Rotate Credentials: Change service account tokens regularly
4. Limit Scope: Grant minimal permissions to service account
5. Review Access: Periodically audit system context usage

Troubleshooting

“Permission Denied” Errors

Check if the operation is running in the expected context:

• User-triggered actions run in User Context with user permissions
• Scheduled actions run in System Context with bot permissions

If a scheduled task fails with permission errors, verify the bot’s service account has the required permissions in Zitadel.

Unexpected “From” Address in Emails

The sender depends on context:

• User Context: Sends as logged-in user
• System Context: Sends as bot account

Ensure your script is triggered in the intended way for the correct sender.

See Also

• Permissions Matrix - Full permission reference
• Bot Authentication - Service account setup
• Security Policy - Security guidelines
• SET SCHEDULE - Scheduled execution