All settings and configurations

This page provides a complete reference for every administrator-configurable setting in Enterprise h2oGPTe, organized by category. It covers what each setting controls, whether it can be overridden at the user or role level, and how to manage settings programmatically.

For step-by-step instructions on managing settings, user overrides, role overrides, and API keys through the System Dashboard UI, see System Settings.

note

The System Dashboard is the administration area in Enterprise h2oGPTe where administrators manage system-wide settings, roles, collections, and monitoring. It is also referred to as the Admin Center in some contexts.

Choosing a management surface

Enterprise h2oGPTe provides settings through three interfaces. Use the following table to choose the right one for your task:

Interface	Best for
System Dashboard UI	Ad-hoc changes, exploration, and one-time configuration.
REST API	Scripting, Terraform/IaC pipelines, and automated provisioning.
Python SDK	Embedding configuration management in Python applications and tooling.

Manage settings from System Dashboard UI

The following tables list all administrator-configurable settings organized by category. Each setting can be managed through the System Dashboard UI, the REST API, or the Python SDK.

Feature settings

Setting	Identifier	Type	User override	Role override	Description
Enable guardrails for new collections by default	default_guardrails_enabled	bool	No	No	Enable PII detection and content filtering guardrails on new collections by default. Individual collections can override this setting.
Enable guardrails for all new chats by default	default_chat_guardrails_enabled	bool	No	No	Enable guardrails for all new chats by default.
Allow users to remove default guardrails from their collections	allow_users_to_remove_default_guardrails	bool	No	No	Allow users, including administrators, to turn off or remove the default guardrail categories on collections that inherited them. Default: true.
Public Mode	public_mode	bool	No	No	Enable public mode for the deployment. Read-only. Set at deployment time.
Whether the system SMTP server is configured	smtp_configured	bool	No	No	Whether the system SMTP server is configured. Read-only. Set via the H2OGPTE_MUX_SMTP_ENABLED environment variable on the mux service, which also sends scheduled-task notification emails (H2OGPTE_MUX_SMTP_HOST, _PORT, _USERNAME, _PASSWORD, _FROM, _USE_TLS). The unprefixed SMTP_* variables configure the separate AI-assistant and file-server senders in the chat and core services and are not read by mux.
Enable the AI Assistants feature	show_ai_assistants	bool	Yes	Yes	Enable the AI Assistants feature. Can be overridden per role and per user. Default: false. The same setting also controls access to Assistant Forums.
Allow users to configure their own Gmail SMTP for scheduled task email notifications	scheduled_task_user_gmail_enabled	bool	Yes	Yes	Allow users to configure their own Gmail SMTP for scheduled task email notifications.
User's Gmail address for email notifications	user_notification_gmail_email	string	Yes	Yes	User's Gmail address for email notifications. Stored as a per-user preference.
User's Gmail app password for email notifications	user_notification_gmail_app_password	string	Yes	Yes	User's Gmail app password for email notifications. Stored as a per-user preference.

note

Some guardrails settings aren't in these tables. An administrator sets H2OGPTE_CORE_PROMPT_GUARD_BACKEND, H2OGPTE_CORE_PROMPT_GUARD_FAIL_CLOSED, and H2OGPTE_CORE_GUARDRAILS_SCAN_FAILURE_ACTION as environment variables at deployment time. See Prompt guard backend and Unreadable guardrail verdicts.

Limit settings

Setting	Identifier	Type	User override	Role override	Description
System-Wide Collection Limit	collection_limit	int	No	No	System-wide maximum number of collections.
Collection Limit Per User	collection_limit_per_user	int	Yes	Yes	Maximum collections per user.
Document Limit Per User	document_limit_per_user	int	Yes	Yes	Maximum documents per user.
Agents Document Limit Per User	agents_document_limit_per_user	int	Yes	Yes	Maximum agent-created documents per user.
Max LLM Cost Per User Per 24h	max_llm_cost_per_user_per_24h	float	Yes	Yes	Rolling 24-hour LLM cost cap per user. Set to -1 to disable.
Max LLM Cost Per User	max_llm_cost_per_user	float	Yes	Yes	Lifetime LLM cost cap per user. Set to -1 to disable.
Max LLM Cost Per Guest	max_llm_cost_per_guest	float	Yes	Yes	LLM cost cap for guest users. Set to -1 to disable.
LLM Cost Units	llm_cost_units	string	No	No	Currency unit for cost tracking (for example, USD).
Collection Expiration Limit (days)	expiration_limit_days	int	No	No	Number of days before expiring collections are archived.
Collection Inactivity Limit (days)	default_collection_inactivity_days	int	No	No	Days of inactivity before a collection begins the expiration process. Set to -1 to disable.
Collection Size Limit	default_collection_size_limit	int64	No	No	Default maximum storage per collection (in bytes). Range: 1 MB to 10 GB.
Chat Session Inactivity Limit (days)	chat_session_inactivity_days	int	No	No	Days of inactivity before a chat session becomes eligible for auto-archive. Set to -1 to turn off inactivity-based auto-archive. Upper bound: 365. See Chat lifecycle.
Chat Session Expiration Limit (days)	chat_expiration_limit_days	int	No	No	Warning window before h2oGPTe archives a chat session, grace period before it deletes an archived chat session, and the ceiling on user-set chat expiry dates. Range: 1 to 365. Changing it re-evaluates every chat session status. See Chat lifecycle.
Global API Key Expiry Limit (days)	global_api_key_expiry_days	int	No	No	Maximum lifetime for API keys (in days). Recommended: 90–365 days to match common security policies.
Max New OIDC Signups Per 24h	maximum_new_users_24h	int	No	No	Maximum new user signups allowed within a 24-hour period.
Max Total Users (System Cap)	maximum_new_users	int	No	No	Total user account cap for the system.
Max Signups Per IP Per Window	signup_rate_limit_per_ip	int	No	No	Maximum signups per IP address within the rate limit window.
Signup Rate Limit Window (Minutes)	signup_rate_limit_window_minutes	int	No	No	Duration (in minutes) of the signup rate limit window.
Output Token Limit	runtime_max_new_tokens	int	Yes	Yes	Maximum output tokens per LLM response.
Max API Requests Per User Per Hour (-1 = unlimited)	api_rate_limit_per_hour	int	Yes	Yes	Maximum API requests per user per hour. Set to -1 to disable rate limiting.
Rate-Limited API Endpoint Patterns	api_rate_limit_endpoints	string	No	No	Comma-separated API endpoint patterns subject to rate limiting. Supports prefix matching with *.
Max WebSocket Messages Per User Per Hour (-1 = unlimited)	ws_rate_limit_per_hour	int	Yes	Yes	Maximum WebSocket messages per user per hour. Set to -1 to disable rate limiting.
Orphaned Document Retention Period (days)	orphaned_document_retention_days	int	No	No	Number of days to retain orphaned documents before deletion. Minimum: 1 day.
Max Concurrent Ingestion Jobs Per User (-1 = unlimited)	crawl_max_concurrent_per_user	int	Yes	Yes	Maximum concurrent document ingestion (crawl) jobs per user. Default: 25. Maximum allowed value: 10000. Enforced independently of crawl_fairness_enabled; cached per user — see Rate Limits and Fairness.
Max Concurrent Chat Sessions Per User (-1 = unlimited)	chat_max_concurrent_per_user	int	Yes	Yes	Maximum simultaneous active chat sessions per user. Default: 100000. Maximum allowed value: 1000000. Enforced independently of chat_fairness_enabled; cached per user — see Rate Limits and Fairness.
Scheduled Task History Retention (days); 0 disables pruning	scheduled_task_execution_retention_days	int	No	No	Number of days to keep scheduled task execution history. Default: 0, which disables pruning. Maximum allowed value: 365.
Chunks used for auto-generated document descriptions (0 disables)	runtime_auto_gen_description_num_chunks	int	No	No	Set to 0 to turn off description auto-generation; regeneration requests then fail—see Regenerating a description. Default: 10.

OAuth settings

Setting	Identifier	Type	Encrypted	Description
SharePoint OAuth Client ID	runtime_sharepoint_oauth_client_id	string	No	SharePoint Online OAuth Client ID.
SharePoint OAuth Client Secret	runtime_sharepoint_oauth_client_secret	string	Yes	SharePoint Online OAuth Client Secret. Stored encrypted.
SharePoint OAuth Tenant ID	runtime_sharepoint_oauth_tenant_id	string	No	Azure AD Tenant ID for SharePoint. Set to your organization's specific tenant ID.
SharePoint OAuth Redirect URL	runtime_sharepoint_oauth_redirect_url	string	No	OAuth redirect URL. Must match the Azure AD app registration.
SharePoint OAuth Scopes	runtime_sharepoint_oauth_scopes	string	No	OAuth scopes for SharePoint access.
Confluence OAuth Client ID	runtime_confluence_oauth_client_id	string	No	Confluence Cloud OAuth Client ID.
Confluence OAuth Client Secret	runtime_confluence_oauth_client_secret	string	Yes	Confluence Cloud OAuth Client Secret. Stored encrypted.
Confluence OAuth Redirect URL	runtime_confluence_oauth_redirect_url	string	No	OAuth redirect URL. Must match the Atlassian app registration.
Confluence OAuth Scopes	runtime_confluence_oauth_scopes	string	No	OAuth scopes for Confluence access.
Snowflake OAuth Client ID	runtime_snowflake_oauth_client_id	string	No	Snowflake OAuth Client ID.
Snowflake OAuth Client Secret	runtime_snowflake_oauth_client_secret	string	No	Snowflake OAuth Client Secret.
Snowflake Account Identifier	runtime_snowflake_account_identifier	string	No	Snowflake Account Identifier (for example, xy12345.us-east-1).
Snowflake OAuth Scopes	runtime_snowflake_oauth_scopes	string	No	OAuth scopes for Snowflake access.
Snowflake OAuth Redirect URL	runtime_snowflake_oauth_redirect_url	string	No	OAuth redirect URL for Snowflake.
Slack OAuth Client ID	runtime_slack_oauth_client_id	string	No	Slack OAuth Client ID. An empty value hides the Slack card on the Data Connectors page.
Slack OAuth Client Secret	runtime_slack_oauth_client_secret	string	Yes	Slack OAuth Client Secret. Stored encrypted.
Slack OAuth Redirect URL	runtime_slack_oauth_redirect_url	string	No	OAuth redirect URL. When unset, falls back to <base URL>/api/v1/connectors/slack/callback. Must match the redirect URL configured in your Slack app.
Slack OAuth Bot Scopes	runtime_slack_oauth_scopes_bot	string	No	Comma-separated bot token scopes. Set this and/or the user scopes; users need at least one to connect Slack.
Slack OAuth User Scopes	runtime_slack_oauth_scopes_user	string	No	Comma-separated user token scopes. Set this and/or the bot scopes; users need at least one to connect Slack.

note

Settings marked as Encrypted are stored securely using AES-GCM encryption. These values are displayed masked in the System Dashboard with a reveal option.

Security settings

Setting	Identifier	Type	Description
Secure Connectors Enabled	secure_connectors_enabled	bool	Enable secure connector mode. Read-only. Set at deployment time.
Secret Manager Enabled	secret_manager_enabled	bool	Enable the secret manager feature. Read-only. Set at deployment time.
Enable signup abuse prevention	signup_abuse_prevention_enabled	bool	Top-level toggle for signup abuse prevention. When enabled, this activates IP rate limiting, daily signup caps, and disposable email blocking.
Enable Disposable Email Blocking	disposable_email_blocking_enabled	bool	Block signups from known disposable or temporary email domains. Active only when signup abuse prevention is also enabled.
Additional Disposable Email Domains (Comma-Separated)	disposable_email_domains_extra	string	Comma-separated list of additional email domains to block during signup.

System settings

Setting	Identifier	Type	User override	Role override	Description
Auto-generated Collection Expiration (days)	adhoc_collection_expiration_days	int	No	No	Number of days before agent-created (ad-hoc) collections expire.
Enable Auto-generated Collection Expiration	enable_adhoc_collection_expiration	bool	No	No	Enable automatic expiration for agent-created collections.
Company Logo URL	company_logo_url	string	Yes	Yes	URL for the company or organization logo displayed in the header.
Chat Logo URL	chat_logo_url	string	Yes	Yes	URL for the logo displayed in the chat interface.
Default Long Job Processing Timeout (secs)	default_long_job_timeout_sec	float	Yes	Yes	Timeout (in seconds) for long-running jobs.
Default Short Job Processing Timeout (secs)	default_short_job_timeout_sec	float	Yes	Yes	Timeout (in seconds) for short-running jobs.
LLMs Configuration	runtime_llms	json	No	No	The list of available LLMs, derived from the LLM registry. Not shown in System Settings. Manage models as described in Configure custom models, and control role access with LLM grants.
Product Name	runtime_product_name	string	Yes	Yes	Product name displayed in the UI and system prompts.
Company Name	runtime_company_name	string	Yes	Yes	Company name displayed in the UI and system prompts.
System Prompt Addendum (LLM)	runtime_system_prompt_addendum_llm	string	No	No	Text appended to every chat-completion system prompt. Leave empty to disable.
System Prompt Addendum (Agent)	runtime_system_prompt_addendum_use_agent	string	No	No	Text appended to every agent system prompt. Leave empty to disable.
Custom HTML Email Notification Template	email_notification_template_html	string	No	No	Custom HTML template for email notifications.
Configuration Cache TTL (seconds)	config_cache_ttl_seconds	int	No	No	Cache TTL for settings flagged as needing per-user propagation (currently show_ai_assistants, crawl_max_concurrent_per_user, chat_max_concurrent_per_user, api_rate_limit_per_hour, and ws_rate_limit_per_hour). Lower values propagate administrator edits faster across mux replicas; higher values reduce database load. Default: 60. Maximum allowed value: 3600.

Manage settings with the REST API

API response fields

Each configuration item returned from the API includes the following fields:

Field	Type	Description
key_name	string	Configuration key (for example, collection_limit_per_user).
string_value	string	Current value represented as a string.
value_type	string	One of: string, bool, int, int64, float, json.
can_overwrite	bool	Whether per-user or per-role overrides are allowed for this setting.
is_public	bool	Whether non-admin users can see this setting.
is_read_only	bool	Whether the setting can be changed at runtime.
upper_bound	int64	Maximum allowed value. -1 indicates no upper bound.
is_encrypted	bool	Whether the value is stored encrypted (applies to OAuth secrets).
category	string	One of: SECURITY, FEATURES, LIMITS, SYSTEM, OAUTH.

List all settings

Retrieve all global configurations with admin-level visibility:

curl -X GET "https://<YOUR_DOMAIN>/api/v1/configurations?as_admin=true" \
  -H "Authorization: Bearer <API_KEY>"

Set a setting

Update a configuration setting by key name:

curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/{key_name}" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value": "<NEW_VALUE>"}'

Reset a setting to default

Remove a configured value and restore the system default for that setting:

curl -X DELETE "https://<YOUR_DOMAIN>/api/v1/configurations/{key_name}" \
  -H "Authorization: Bearer <API_KEY>"

Manage settings with the Python SDK

from h2ogpte import H2OGPTE

client = H2OGPTE(address="https://<YOUR_DOMAIN>", api_key="<API_KEY>")

# List all settings
configs = client.get_global_configurations_by_admin()
for c in configs:
    print(f"{c.key_name} = {c.string_value} (type={c.value_type}, overridable={c.can_overwrite})")

# Set a setting
client.set_global_configuration(
    "default_guardrails_enabled", "true", can_overwrite=False, is_public=True
)

Recommended production configuration

The following settings are recommended for new deployments to establish a strong security posture. Apply them in the order listed for a complete baseline configuration.

Enable guardrails

Enable PII detection and content filtering for all new collections:

curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/default_guardrails_enabled" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value":"true"}'

note

To learn more about guardrails configuration and enforcement hierarchy, see Global Guardrails.

Set API key expiration

Set the global API key expiration window:

curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/global_api_key_expiry_days" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value":"365"}'

Enable signup abuse prevention

Control user provisioning with rate limiting and disposable email blocking:

# Enable signup abuse prevention
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/signup_abuse_prevention_enabled" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value":"true"}'

# Set maximum new users per 24 hours
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/maximum_new_users_24h" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value":"100"}'

# Set signup rate limit per IP
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/signup_rate_limit_per_ip" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value":"3"}'

Configure collection lifecycle

Enable automatic data cleanup to manage retention and storage:

# Set collection expiration window
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/expiration_limit_days" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value":"90"}'

# Enable inactivity-based cleanup
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/default_collection_inactivity_days" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value":"90"}'

# Enable automatic cleanup for agent-created collections
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/enable_adhoc_collection_expiration" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value":"true"}'

Related topics

• System Settings - Manage settings through the System Dashboard UI
• Roles and Permissions Reference - Configure per-role overrides
• APIs - Use API keys for programmatic access to Enterprise h2oGPTe
• Use a knowledge graph for collection retrieval - Configure Graph RAG build and retrieval behavior with H2OGPTE_CORE_GRAPH_RAG_* environment variables

---

Feedback

• Submit and view feedback for this page
• Send feedback about Enterprise h2oGPTe to cloud-feedback@h2o.ai