docs/multiuser/specification.md
This document provides a comprehensive specification for adding multi-user support to InvokeAI. The feature will enable a single InvokeAI instance to support multiple isolated users, each with their own generation settings, image boards, and workflows, while maintaining administrative controls for model management and system configuration.
Capabilities:
Restrictions:
Capabilities:
Restrictions:
First-time Launch Flow:
Reset Capability:
Flow:
Invitation Email Flow:
User Self-Service:
Administrator Actions:
User-Initiated (Future Enhancement):
Administrator-Initiated:
CREATE TABLE users (
user_id TEXT NOT NULL PRIMARY KEY,
email TEXT NOT NULL UNIQUE,
display_name TEXT,
password_hash TEXT NOT NULL,
is_admin BOOLEAN NOT NULL DEFAULT FALSE,
is_active BOOLEAN NOT NULL DEFAULT TRUE,
created_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
updated_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
last_login_at DATETIME
);
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_is_admin ON users(is_admin);
CREATE INDEX idx_users_is_active ON users(is_active);
CREATE TABLE user_sessions (
session_id TEXT NOT NULL PRIMARY KEY,
user_id TEXT NOT NULL,
token_hash TEXT NOT NULL,
expires_at DATETIME NOT NULL,
created_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
last_activity_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
user_agent TEXT,
ip_address TEXT,
FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
);
CREATE INDEX idx_user_sessions_user_id ON user_sessions(user_id);
CREATE INDEX idx_user_sessions_expires_at ON user_sessions(expires_at);
CREATE INDEX idx_user_sessions_token_hash ON user_sessions(token_hash);
CREATE TABLE user_invitations (
invitation_id TEXT NOT NULL PRIMARY KEY,
email TEXT NOT NULL,
token_hash TEXT NOT NULL,
invited_by_user_id TEXT NOT NULL,
expires_at DATETIME NOT NULL,
used_at DATETIME,
created_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
FOREIGN KEY (invited_by_user_id) REFERENCES users(user_id) ON DELETE CASCADE
);
CREATE INDEX idx_user_invitations_email ON user_invitations(email);
CREATE INDEX idx_user_invitations_token_hash ON user_invitations(token_hash);
CREATE INDEX idx_user_invitations_expires_at ON user_invitations(expires_at);
CREATE TABLE shared_boards (
board_id TEXT NOT NULL,
user_id TEXT NOT NULL,
permission TEXT NOT NULL CHECK(permission IN ('read', 'write', 'admin')),
created_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
PRIMARY KEY (board_id, user_id),
FOREIGN KEY (board_id) REFERENCES boards(board_id) ON DELETE CASCADE,
FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
);
CREATE INDEX idx_shared_boards_user_id ON shared_boards(user_id);
CREATE INDEX idx_shared_boards_board_id ON shared_boards(board_id);
-- Add columns:
ALTER TABLE boards ADD COLUMN user_id TEXT NOT NULL DEFAULT 'system';
ALTER TABLE boards ADD COLUMN is_shared BOOLEAN NOT NULL DEFAULT FALSE;
ALTER TABLE boards ADD COLUMN created_by_user_id TEXT;
-- Add foreign key (requires recreation in SQLite):
FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
FOREIGN KEY (created_by_user_id) REFERENCES users(user_id) ON DELETE SET NULL
-- Add indices:
CREATE INDEX idx_boards_user_id ON boards(user_id);
CREATE INDEX idx_boards_is_shared ON boards(is_shared);
-- Add column:
ALTER TABLE images ADD COLUMN user_id TEXT NOT NULL DEFAULT 'system';
-- Add foreign key:
FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
-- Add index:
CREATE INDEX idx_images_user_id ON images(user_id);
-- Add columns:
ALTER TABLE workflows ADD COLUMN user_id TEXT NOT NULL DEFAULT 'system';
ALTER TABLE workflows ADD COLUMN is_public BOOLEAN NOT NULL DEFAULT FALSE;
-- Add foreign key:
FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
-- Add indices:
CREATE INDEX idx_workflows_user_id ON workflows(user_id);
CREATE INDEX idx_workflows_is_public ON workflows(is_public);
-- Add column:
ALTER TABLE session_queue ADD COLUMN user_id TEXT NOT NULL DEFAULT 'system';
-- Add foreign key:
FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
-- Add index:
CREATE INDEX idx_session_queue_user_id ON session_queue(user_id);
-- Add columns:
ALTER TABLE style_presets ADD COLUMN user_id TEXT NOT NULL DEFAULT 'system';
ALTER TABLE style_presets ADD COLUMN is_public BOOLEAN NOT NULL DEFAULT FALSE;
-- Add foreign key:
FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
-- Add indices:
CREATE INDEX idx_style_presets_user_id ON style_presets(user_id);
CREATE INDEX idx_style_presets_is_public ON style_presets(is_public);
{ email, display_name, password }{ success, user }{ email, password, remember_me? }{ token, user, expires_at }Authorization: Bearer <token>{ success }Authorization: Bearer <token>{ user }{ current_password, new_password }Authorization: Bearer <token>{ success }offset, limit, search, role_filter{ users[], total, offset, limit }{ email, display_name, is_admin, send_invitation?, initial_password? }{ user, invitation_link? }{ user }{ display_name?, is_admin?, is_active? }{ user }delete_data (true/false){ success }{ success, reset_link }{ user_ids[], permission: 'read' | 'write' | 'admin' }{ success, shared_with[] }{ shares[] }{ success }All existing endpoints will be modified to:
Example modifications:
GET /api/v1/boards → Returns only user's boards + shared boardsPOST /api/v1/session/queue → Associates queue item with current userGET /api/v1/queue → Returns all items for admin, only user's items for regular usersNew Redux slices/zustand stores:
authSlice: Current user, authentication status, tokenusersSlice: User list for admin interfacesharingSlice: Board sharing stateUpdated slices:
boardsSlice: Include shared boards, ownership infoqueueSlice: Include user filteringworkflowsSlice: Include public/private statusAdd to InvokeAIAppConfig:
# Authentication
auth_enabled: bool = True # Enable/disable multi-user auth
session_expiry_hours: int = 24 # Default session expiration
session_expiry_hours_remember: int = 168 # "Remember me" expiration (7 days)
password_min_length: int = 8 # Minimum password length
require_strong_passwords: bool = True # Enforce password complexity
# Session tracking
enable_server_side_sessions: bool = False # Optional server-side session tracking
# Audit logging
audit_log_auth_events: bool = True # Log authentication events
audit_log_admin_actions: bool = True # Log administrative actions
# Email (optional - for invitations and password reset)
email_enabled: bool = False
smtp_host: str = ""
smtp_port: int = 587
smtp_username: str = ""
smtp_password: str = ""
smtp_from_address: str = ""
smtp_from_name: str = "InvokeAI"
# Initial admin (stored as hash)
admin_email: Optional[str] = None
admin_password_hash: Optional[str] = None
auth_enabled = False, system runs in legacy single-user modeNote: Email/SMTP configuration is optional. Many administrators will not have ready access to an outgoing SMTP server. When email is not configured, the system provides fallback mechanisms by displaying setup links directly in the admin UI.
Subject: You've been invited to InvokeAI
Hello,
You've been invited to join InvokeAI by [Administrator Name].
Click the link below to set up your account:
[Setup Link]
This link expires in 7 days.
---
InvokeAI
Subject: Reset your InvokeAI password
Hello [User Name],
A password reset was requested for your account.
Click the link below to reset your password:
[Reset Link]
This link expires in 24 hours.
If you didn't request this, please ignore this email.
---
InvokeAI
| Risk | Impact | Probability | Mitigation |
|---|---|---|---|
| Performance degradation with user filtering | Medium | Low | Index optimization, query caching |
| Database migration failures | High | Low | Thorough testing, rollback procedures |
| Session management complexity | Medium | Medium | Use proven libraries (PyJWT), extensive testing |
| Auth bypass vulnerabilities | High | Low | Security review, penetration testing |
| Risk | Impact | Probability | Mitigation |
|---|---|---|---|
| Confusion in migration for existing users | Medium | High | Clear documentation, migration wizard |
| Friction from additional login step | Low | High | Remember me option, long session timeout |
| Complexity of admin interface | Medium | Medium | Intuitive UI design, user testing |
| Risk | Impact | Probability | Mitigation |
|---|---|---|---|
| Email delivery failures | Low | Medium | Show links in UI, document manual methods |
| Lost admin password | High | Low | Document recovery procedure, config reset |
| User data conflicts in migration | Medium | Low | Data validation, backup requirements |
The following design decisions have been approved for implementation:
OAuth2 Priority: OAuth2/OpenID Connect integration will be a future enhancement. The initial release will focus on username/password authentication to keep scope manageable.
Email Requirement: Email/SMTP configuration is optional. Many administrators will not have ready access to an outgoing SMTP server. The system will provide fallback mechanisms (showing setup links directly in the admin UI) when email is not configured.
Data Migration: During migration from single-user to multi-user mode, the administrator will be given the option to specify an arbitrary user account to hold legacy data. The admin account can be used for this purpose if the administrator wishes.
API Compatibility: Authentication will be required on all APIs, but authentication will not be required if multi-user support is disabled (backward compatibility mode with auth_enabled: false).
Session Storage: The system will use JWT tokens with optional server-side session tracking. This provides scalability while allowing administrators to enable server-side tracking if needed.
Audit Logging: The system will log authentication events and admin actions. This provides accountability and security monitoring for critical operations.
This specification provides a comprehensive blueprint for implementing multi-user support in InvokeAI. The design prioritizes:
The phased implementation approach allows for iterative development and testing, while the detailed specifications ensure all stakeholders have clear expectations of the final system.