> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/stormkit-io/stormkit-io/llms.txt
> Use this file to discover all available pages before exploring further.
# Managing Users
> Control user access to your self-hosted Stormkit instance with sign-up modes, domain whitelisting, and approval workflows
**Available since:** Stormkit v1.25.0
User management allows administrators to control who can sign up and access your self-hosted Stormkit instance. This feature provides fine-grained control over user registrations, making it ideal for organizations that need to restrict access to specific team members or domains.
## Accessing User Management
Click on your **profile** in the top right corner.
Select **Admin** from the dropdown menu.
Navigate to **Authentication** or go directly to `/admin/auth-config`.
## Sign-Up Modes
Stormkit offers three different sign-up modes to control how users can register for your instance.
### Off (No New Users Allowed)
* **Completely disables** new user registrations
* **Existing users** can continue to log in normally
* **Use case**: Lock down your instance to current users only
With this mode enabled, no new users can register, even if they have valid credentials from configured Git providers.
### On (All Users Allowed)
* **Allows anyone** to sign up freely
* **New users** are automatically approved upon registration
* **No approval** required
* **Use case**: Open environments, development instances, or public deployments
This is the most permissive mode and is suitable for development environments where you want easy access for team members.
### Approval Mode (Waitlist)
**Enterprise Edition only** - This feature requires an Enterprise Edition license.
* **Requires admin approval** for new user registrations
* Users can sign up, but their **accounts remain pending** until approved
* Supports **domain-based whitelisting** for automatic approval
* **Use case**: Production environments requiring strict access control
## Domain Whitelisting
**Enterprise Edition only** - Domain whitelisting requires an Enterprise Edition license.
When using **Approval Mode**, you can configure domain whitelisting to automatically approve or deny users based on their email domain.
### Allow Specific Domains
To automatically approve users from specific domains, enter the domains separated by commas:
```
example.org, stormkit.io, yourcompany.com
```
Users with email addresses from these domains will be **automatically approved**, while all others will require manual approval.
**Example:**
* `user@example.org` → ✅ Auto-approved
* `user@stormkit.io` → ✅ Auto-approved
* `user@gmail.com` → ⏳ Requires approval
### Deny Specific Domains
To automatically reject users from specific domains, prefix each domain with an exclamation mark (`!`):
```
!spam.com, !blocked-domain.org, !competitor.com
```
Users with email addresses from these domains will be **automatically rejected**, while all others will require manual approval.
**Example:**
* `user@spam.com` → ❌ Auto-rejected
* `user@blocked-domain.org` → ❌ Auto-rejected
* `user@gmail.com` → ⏳ Requires approval
**Important:** You cannot mix allowed and denied domains in the same whitelist. All domains must either be in allow mode (without `!`) or deny mode (with `!`).
### Domain Matching Rules
* Domain matching is **case-insensitive**
* Whitespace around domains is automatically trimmed
* Subdomains are **not** automatically included (e.g., `example.com` does not match `subdomain.example.com`)
## Managing Pending Users
**Enterprise Edition only** - Pending user management requires an Enterprise Edition license.
When Approval Mode is enabled, users who sign up will appear in the **Pending Users** section.
### Approving Users
Scroll to the **Pending Users** section in `/admin/auth-config`.
Check the boxes next to users you want to approve.
Click the **Approve** button.
Approved users will receive immediate access to the Stormkit instance.
### Rejecting Users
Go to the **Pending Users** section in `/admin/auth-config`.
Check the boxes next to users you want to reject.
Click the **Reject** button.
Rejected users will be removed from the pending list and cannot access the instance.
Rejected users can attempt to sign up again, but they will re-enter the pending state unless their domain is on the deny list.
## Configuration Examples
### Scenario 1: Company-Only Access
**Goal:** Only allow users with `@yourcompany.com` email addresses.
**Configuration:**
* **Sign-up mode:** Approval Mode (Enterprise Edition)
* **Domain whitelist:** `yourcompany.com`
**Result:**
* `employee@yourcompany.com` → ✅ Auto-approved
* `contractor@gmail.com` → ⏳ Requires manual approval
### Scenario 2: Block Competitors
**Goal:** Automatically reject users from known competitor domains.
**Configuration:**
* **Sign-up mode:** Approval Mode (Enterprise Edition)
* **Domain whitelist:** `!competitor1.com, !competitor2.com`
**Result:**
* `user@competitor1.com` → ❌ Auto-rejected
* `user@anywhere-else.com` → ⏳ Requires manual approval
### Scenario 3: Development Environment
**Goal:** Allow anyone to sign up during development.
**Configuration:**
* **Sign-up mode:** On (All users allowed)
* **Domain whitelist:** (not applicable)
**Result:**
* All users → ✅ Auto-approved
### Scenario 4: Locked Production Instance
**Goal:** Prevent any new registrations in production.
**Configuration:**
* **Sign-up mode:** Off (No new users)
**Result:**
* All new users → ❌ Registration disabled
* Existing users → ✅ Can still log in
## Best Practices
### Security Recommendations
Follow these security best practices for user management:
* **Use Approval Mode** for production environments to maintain strict access control
* **Configure domain whitelisting** to reduce manual approval overhead for trusted domains
* **Regularly review** pending users to ensure timely access for legitimate users
* **Monitor user activity** through audit logs
* **Remove access** for inactive or former team members promptly
### Operational Guidelines
* **Set clear policies** on who should have access
* **Document approval criteria** for your team
* **Respond to pending users** within a reasonable timeframe (e.g., 24 hours)
* **Communicate changes** to sign-up policies with your team
* **Test configuration changes** in a non-production environment first
### Domain Whitelist Tips
* Start with a **narrow whitelist** and expand as needed
* Use **deny lists** sparingly - they require ongoing maintenance
* Consider **subdomains** carefully (they must be listed explicitly)
* Keep the whitelist **up to date** when your organization changes email domains
## Technical Notes
### Persistence
* User management configuration is **stored in the database**
* Settings **persist across service restarts**
* Configuration changes take effect **immediately**
### Behavior Details
* Changes to sign-up mode affect **new registrations immediately**
* **Existing approved users** are not affected by configuration changes
* **Existing pending users** are affected by changes to domain whitelisting
* Domain matching is **case-insensitive** for email addresses
### Database Storage
User registration data is stored in PostgreSQL:
```bash theme={null}
# Database configuration
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=stormkit_db
POSTGRES_USER=stormkit_admin
```
## Troubleshooting
### Users Not Appearing in Pending List
**Possible causes:**
* Sign-up mode is set to "On" (auto-approval enabled)
* User's domain is in the allow whitelist (auto-approved)
* User already has an approved account
**Solution:**
* Verify sign-up mode is set to "Approval Mode"
* Check domain whitelist configuration
* Search for the user in approved users list
### Domain Whitelist Not Working
**Possible causes:**
* Mixed allow/deny domains (not supported)
* Extra whitespace in domain names
* Subdomain matching expectations
**Solution:**
* Ensure all domains use consistent format (all allow or all deny)
* Trim whitespace around domain names
* Add subdomains explicitly if needed
### Cannot Enable Approval Mode
**Cause:** Approval Mode requires an Enterprise Edition license.
**Solution:**
* Upgrade to Enterprise Edition
* Use "On" or "Off" modes (available in Community Edition)
## Environment Variables
User management doesn't require specific environment variables, but relies on core Stormkit configuration:
```bash .env theme={null}
# Database connection (required)
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_DB=stormkit_db
POSTGRES_USER=stormkit_admin
POSTGRES_PASSWORD=your_password
# Application URLs (required)
STORMKIT_APP_URL=https://yourdomain.com
STORMKIT_API_URL=https://api.yourdomain.com
```
## Next Steps
Configure Git provider authentication
Build custom Docker images