Users

SystemPrompt is multi-tenant from the first line of code. Every user belongs to a tenant. Every operation is scoped to a tenant. Every query is filtered by tenant. This isn't a feature you enable—it's how the platform works.

When you ship an AI product to your users, each user gets isolated access. User A cannot see User B's conversations, agents, or data. This isolation is enforced at the database level, not just the application level. Even if application code has bugs, tenant boundaries cannot be crossed.

Multi-Tenant Architecture

Multi-tenancy in SystemPrompt follows the shared database, shared schema pattern with row-level isolation. All tenants share the same database and tables, but every row has a tenant_id column. All queries automatically include tenant filtering.

Tenant hierarchy:

Tenant (organization/account)
└── Users (people who authenticate)
    └── Sessions (active login sessions)
        └── Tokens (API access credentials)

A tenant represents an isolated workspace. In a B2B SaaS application, each tenant might be a customer organization. In a consumer application, each tenant might be an individual user. The systemprompt-users crate manages this hierarchy.

Automatic isolation:

When a request arrives, the system extracts the tenant ID from the authentication token. This tenant ID is injected into the database query context. Every query that touches tenant-scoped data automatically includes a WHERE tenant_id = ? clause.

// Conceptual example - actual implementation in systemprompt-users
let users = user_repository
    .list()
    .for_tenant(ctx.tenant_id)  // Automatic tenant scoping
    .execute()
    .await?;

The systemprompt-identifiers crate provides strongly-typed identifiers for users, tenants, and other entities. Using UserId instead of raw strings prevents identifier confusion bugs.

User Management and Profiles

Users are authenticated principals within a tenant. Each user has a profile containing identity information and preferences.

User properties:

Property	Description
id	Unique user identifier (UserId type)
tenant_id	Owning tenant (TenantId type)
email	Primary email address
display_name	Human-readable name
avatar_url	Profile image URL
role	User role within tenant
created_at	Registration timestamp
last_login_at	Most recent authentication

CLI user management:

# List users in current tenant
systemprompt admin users list

# Show user details
systemprompt admin users show <user_id>

# Create a new user
systemprompt admin users create --email user@example.com --role user

# Update user role
systemprompt admin users update <user_id> --role admin

User roles:

Roles provide a coarse-grained permission model layered on top of OAuth2 scopes.

Role	Description	Typical Scopes
viewer	Read-only access	user, agents:read
user	Standard operations	user, agents:read, tools:execute
admin	Full tenant access	admin, all scopes
owner	Tenant owner	admin, billing, user management

Per-User Scope Enforcement

Scopes define what operations a user can perform. They are granted during authentication and checked on every protected operation.

How scope enforcement works:

1. User authenticates (WebAuthn or OAuth2)
2. System determines user's role and permissions
3. Access token is issued with appropriate scopes
4. Every API call extracts scopes from token
5. Operation requirements are checked against token scopes
6. Request proceeds or returns 403 Forbidden

Scope assignment:

Scopes can be assigned at multiple levels:

• Role-based: Roles map to default scope sets
• User-specific: Individual users can have additional scopes
• Client-specific: OAuth2 clients can request specific scopes
• Context-specific: Operations can require contextual scopes

# Agent configuration with scope requirements
security:
  - oauth2: ["user"]  # Requires at least 'user' scope

Scope verification:

The authorization layer checks scopes before any protected operation. This happens in middleware, before business logic executes.

# Check current session scopes
systemprompt admin session show

# Output includes granted scopes
# scopes: ["user", "agents:read", "tools:execute"]

Tenant Isolation Boundaries

Tenant isolation is the security foundation of multi-tenant applications. SystemPrompt enforces isolation at multiple levels.

Database level:

Every table with tenant-scoped data includes a tenant_id column. Database queries automatically filter by tenant. Even raw SQL queries through the database crate include tenant context.

Application level:

Service methods receive a context object containing the authenticated tenant. Services use this context for all data access. Cross-tenant access requires explicit system-level authorization.

API level:

API endpoints extract tenant context from authentication tokens. Requests without valid tenant context are rejected. Admin endpoints can access cross-tenant data with appropriate scopes.

File storage level:

Uploaded files are stored in tenant-scoped paths. The file service enforces tenant boundaries when serving or modifying files.

Isolation verification:

The test suite includes isolation verification tests. These tests create data in one tenant and verify it's invisible from another tenant. Any isolation breach fails the test suite.

Tenant Configuration

Tenants are provisioned through the cloud management system. Each tenant has configuration that controls behavior.

Tenant settings:

# Tenant configuration (managed via cloud API)
tenant:
  id: "tenant_abc123"
  name: "Acme Corp"
  plan: "professional"
  settings:
    max_users: 50
    max_agents: 10
    storage_quota_gb: 100
  features:
    - custom_domains
    - advanced_analytics

Provisioning a tenant:

# Create a new tenant (cloud admin only)
systemprompt cloud tenants create --name "Acme Corp" --plan professional

# List all tenants
systemprompt cloud tenants list

# Switch to a tenant context
systemprompt cloud profile switch --tenant tenant_abc123

User Sessions

Sessions track active logins. A user can have multiple active sessions (different devices). Sessions have expiration times and can be revoked.

Session management:

# List active sessions
systemprompt admin sessions list

# Revoke a specific session
systemprompt admin sessions revoke <session_id>

# Revoke all sessions for a user
systemprompt admin sessions revoke-all --user <user_id>

Session properties:

Property	Description
id	Session identifier
user_id	Owning user
tenant_id	Tenant context
created_at	Login timestamp
expires_at	Session expiration
ip_address	Client IP (for audit)
user_agent	Client description

Configuration Reference

Item	Location	Description
User profiles	Database	User identity and preferences
Tenant settings	Cloud API	Tenant configuration
Session data	Database	Active login sessions
Credentials	.systemprompt/credentials.json	Cloud authentication

CLI Reference

Command	Description
systemprompt admin users list	List users with pagination and filtering
systemprompt admin users show <id>	Show detailed user information
systemprompt admin users search <query>	Search users by name, email, or full name
systemprompt admin users create	Create a new user
systemprompt admin users update <id>	Update user fields
systemprompt admin users delete <id>	Delete a user
systemprompt admin users count	Get total user count
systemprompt admin users export	Export users to JSON
systemprompt admin users stats	Show user statistics dashboard
systemprompt admin users merge <source> <target>	Merge source user into target user
systemprompt admin users bulk	Bulk operations on users
systemprompt admin users role	Role management commands
systemprompt admin users session	Session management commands
systemprompt admin users ban	IP ban management commands

See systemprompt admin users <command> --help for detailed options.