¶ API Key Wildcard
¶ Table of Contents
- Requirements
- Installation
- Usage
- Troubleshooting
- Technical Details
- Security Considerations
- Best Practices
- FAQ
¶ Overview
The API Key Wildcard Plugin provides a separate API endpoint (/api/wildcard/tickets.json) that allows API keys with IP address 0.0.0.0 to accept requests from any IP address.
This solves a common development problem: osTicket's native API requires you to specify a specific IP address for each API key. This is secure for production, but cumbersome during development when your IP address changes frequently (dynamic IP, working from different locations, CI/CD pipelines).
¶ ⚠️ Security Warning
CRITICAL: Only use wildcard API keys (0.0.0.0) in development environments!
In production environments, API keys should always be bound to specific IP addresses for security reasons.
Why this is important:
- 🔒 API keys with
0.0.0.0accept requests from ANY IP address worldwide - 🔒 Anyone who obtains your API key could create tickets from anywhere
- 🔒 Production systems should use restrictive IP whitelisting
Safe usage:
- ✅ Development environments (localhost)
- ✅ Internal networks behind firewalls
- ✅ Testing/staging environments
- ❌ Public-facing production servers
¶ Key Features
- ✅ Separate Wildcard Endpoint - Standard API remains unchanged and secure
- ✅ No Core Modifications - True plugin, can be easily enabled/disabled
- ✅ Automatic Installation - Just enable the plugin, no manual file copying
- ✅ Automatic Updates - Version detection and auto-update on plugin file changes
- ✅ Apache & NGINX Support - Works with both web servers
¶ Use Cases
- Local Development - Your home IP address changes frequently (dynamic IP)
- API Integration Testing - Testing from different servers/locations without updating IP
- MCP Servers - claude-mcp-osTicket integration with changing IPs
- CI/CD Pipelines - Automated testing with dynamic IPs (non-production)
- Team Development - Developers working from various locations (home, office, coffee shop)
¶ Requirements
| Requirement | Version | Notes |
|---|---|---|
| osTicket | 1.18.x | Plugin uses osTicket's native API infrastructure |
| PHP | 7.4+ | Recommended: PHP 8.1+ for best performance |
| Web Server | Apache or NGINX | Apache requires mod_rewrite enabled |
| File Permissions | Write access to /api/ |
Required for automatic installation |
¶ Installation
¶ Step 1: Install Plugin Files
¶ Method 1: ZIP Download (Recommended)
- Download latest release from Releases
- Extract ZIP file
- Upload
api-key-wildcardfolder to/include/plugins/on your osTicket server
Final path: /path/to/osticket/include/plugins/api-key-wildcard/
¶ Method 2: Git Repository
cd /path/to/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-api-key-wildcard.git
¶ Step 2: Enable Plugin in osTicket
- Login to osTicket Admin Panel
- Navigate to: Admin Panel → Manage → Plugins
- Find "API Key Wildcard Support" in the plugin list
- Click Enable
What happens automatically:
- ✅ Copies
wildcard.phpto/api/directory - ✅ Updates
/api/.htaccesswith required rewrite rules - ✅ Sets correct file permissions
- ✅ Logs installation details to error log
No manual configuration needed!
¶ Step 3: Create API Key with 0.0.0.0
- Go to Admin Panel → Manage → API Keys
- Click Add New API Key
- Set IP Address to:
0.0.0.0 - Enable Can Create Tickets: ✅ Yes
- Save and copy the generated API key
Important: The API key MUST have IP 0.0.0.0 to work with the wildcard endpoint!
¶ Manual Installation (If Automatic Installation Fails)
If the automatic installation fails (e.g., due to file permissions):
-
Copy wildcard endpoint:
cp /path/to/osticket/include/plugins/api-key-wildcard/wildcard.php \ /path/to/osticket/api/wildcard.php chmod 755 /path/to/osticket/api/wildcard.php -
Update
/api/.htaccess- Add these lines afterRewriteEngine On:# Disable MultiViews for wildcard endpoint (prevents mod_negotiation) Options -MultiViews # Wildcard API endpoint (must come BEFORE the default rule) RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^wildcard/(.*)$ wildcard.php/$1 [L] -
Verify permissions:
chmod 755 /path/to/osticket/api/wildcard.php chmod 644 /path/to/osticket/api/.htaccess
¶ NGINX Configuration
If using NGINX, manually add this to your server block:
# osTicket API Key Wildcard Plugin
location ~ ^/api/wildcard/ {
rewrite ^/api/wildcard/(.*)$ /api/wildcard.php/$1 last;
}
# Pass PHP requests to PHP-FPM
location ~ ^/api/wildcard\.php {
fastcgi_split_path_info ^(/api/wildcard\.php)(/.+)$;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
include fastcgi_params;
fastcgi_pass unix:/var/run/php/php-fpm.sock; # Adjust to your PHP-FPM socket
}
After adding:
- Test configuration:
sudo nginx -t - Reload NGINX:
sudo systemctl reload nginx
¶ Usage
¶ Endpoint Comparison
| Feature | Standard API | Wildcard API |
|---|---|---|
| Endpoint | /api/tickets.json |
/api/wildcard/tickets.json |
| IP Restriction | Specific IP required | Any IP (if API key is 0.0.0.0) |
| Security | High (production-ready) | Low (development only) |
| Use Case | Production | Development/Testing |
¶ Example: Create Ticket with curl
curl -X POST \
-H "X-API-Key: YOUR_API_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"name": "Test User",
"email": "test@example.com",
"subject": "Test Ticket",
"message": "This is a test message"
}' \
http://localhost/osTicket/api/wildcard/tickets.json
Important:
- Use
/api/wildcard/tickets.json(NOT/api/tickets.json) - API key MUST be set to IP
0.0.0.0 - Standard API endpoint continues to work normally
¶ Supported API Endpoints
All standard osTicket API endpoints work through wildcard:
| Standard Endpoint | Wildcard Endpoint |
|---|---|
/api/tickets.json |
/api/wildcard/tickets.json |
/api/tickets/:id.json |
/api/wildcard/tickets/:id.json |
Note: Works with extended API endpoints from other plugins too!
¶ Troubleshooting
¶ Problem: Automatic Installation Failed
Symptoms: Plugin enabled but wildcard endpoint doesn't work
Check:
- File exists:
ls /path/to/osticket/api/wildcard.php - Error log:
tail -f /var/log/apache2/error.log - File permissions: File must be readable by web server
Solution: Use manual installation (see installation section above)
¶ Problem: 401 Unauthorized Error
Symptoms: Request to wildcard endpoint returns 401
Possible causes:
-
API key not set to 0.0.0.0
- Solution: Admin Panel → API Keys → Edit key → Set IP to
0.0.0.0
- Solution: Admin Panel → API Keys → Edit key → Set IP to
-
Using wrong endpoint
- Solution: Use
/api/wildcard/tickets.json(NOT/api/tickets.json)
- Solution: Use
-
API key disabled
- Solution: Admin Panel → API Keys → Enable key
-
Missing X-API-Key header
- Solution: Include header:
X-API-Key: YOUR_KEY
- Solution: Include header:
¶ Problem: 404 Not Found Error
Symptoms: /api/wildcard/tickets.json returns 404
Possible causes:
-
wildcard.php not copied to /api/ directory
ls /path/to/osticket/api/wildcard.phpSolution: Enable/disable plugin to trigger installation, or copy manually
-
.htaccess rewrite rule missing
cat /path/to/osticket/api/.htaccess | grep wildcardSolution: Manually add rewrite rule (see installation section)
-
mod_rewrite not enabled (Apache)
apache2ctl -M | grep rewriteSolution:
sudo a2enmod rewrite sudo systemctl restart apache2 -
MultiViews causing issues (Apache)
Solution: Ensure.htaccesscontainsOptions -MultiViewsBEFORE rewrite rules
¶ Problem: Plugin Updates Not Applied
Symptoms: Updated plugin files, but wildcard.php in /api/ is still old version
Solution:
- Check plugin version in Admin Panel → Plugins
- Clear PHP OpCode cache:
# For PHP-FPM sudo systemctl reload php8.1-fpm # For Apache mod_php sudo systemctl reload apache2 - Manually trigger update by disabling/enabling plugin
- If still not working, manually copy files
¶ Technical Details
¶ Architecture
┌─────────────────────────────────────┐
│ Client (any IP) │
├─────────────────────────────────────┤
│ HTTP Request │
│ POST /api/wildcard/tickets.json │
│ X-API-Key: YOUR_KEY_WITH_0.0.0.0 │
├─────────────────────────────────────┤
│ Apache mod_rewrite / NGINX │
│ .htaccess: ^wildcard/(.*)$ │
│ → wildcard.php/$1 │
├─────────────────────────────────────┤
│ wildcard.php │
│ - Checks if API key has IP 0.0.0.0 │
│ - If yes: Allow request │
│ - If no: Reject (401 Unauthorized) │
├─────────────────────────────────────┤
│ osTicket API Processing │
│ (standard ticket creation logic) │
└─────────────────────────────────────┘
¶ File Structure
api-key-wildcard/
├── plugin.php # Plugin registration
├── class.ApiKeyWildcard.php # Main plugin class
├── wildcard.php # API endpoint (copied to /api/)
├── api.wildcard.inc.php # API implementation logic
└── CHANGELOG.md # Version history
¶ Automatic Installation Logic
The plugin uses osTicket's enable() hook:
- Check if
/api/wildcard.phpexists - If not, copy from plugin directory
- Set file permissions (755)
- Check if
.htaccesscontains wildcard rule - If not, append rewrite rule
- Log success/failure to error log
¶ Version Tracking
Plugin tracks installed versions for automatic updates:
# In .htaccess:
# API Key Wildcard Plugin v1.0.0
On plugin enable:
- Extract version from
.htaccesscomment - Compare with current plugin version
- If different: Re-copy files and update version
- Log update to error log
¶ Security Mechanism
Standard API (/api/tickets.json):
// Checks IP address against API key configuration
if ($api_key->getIpAddr() !== $_SERVER['REMOTE_ADDR']) {
return 401 Unauthorized;
}
Wildcard API (/api/wildcard/tickets.json):
// Only allows API keys with 0.0.0.0
if ($api_key->getIpAddr() !== '0.0.0.0') {
return 401 Unauthorized; // Must use standard API
}
// Skip IP check for 0.0.0.0 keys
¶ Security Considerations
¶ When NOT to Use This Plugin
NEVER use wildcard API keys (0.0.0.0) in:
- ❌ Public-facing production servers
- ❌ Servers handling sensitive data
- ❌ Compliance-regulated environments (PCI-DSS, HIPAA, etc.)
- ❌ Shared hosting environments
¶ Safe Usage Scenarios
Safe to use wildcard API keys in:
- ✅ Development environments (localhost)
- ✅ Internal networks behind firewalls
- ✅ Testing/staging environments (non-public)
- ✅ Personal projects with low security requirements
¶ Attack Scenarios
What could go wrong with wildcard keys:
-
Leaked API Key
- Attacker finds key in Git repository
- Creates spam tickets from anywhere
- Mitigation: Never commit
.envfiles, use.gitignore
-
Brute Force Attacks
- Attacker tries to guess API key
- No IP restriction to limit attempts
- Mitigation: Use strong, randomly generated API keys
-
Internal Threat
- Disgruntled employee uses wildcard key
- Can create/modify tickets from any location
- Mitigation: Separate keys per developer, revoke access on termination
¶ Additional Security Layers
If using wildcard keys, add protection:
- 🔒 Firewall rules limiting access to osTicket
- 🔒 VPN access only
- 🔒 IP whitelisting at firewall level
- 🔒 HTTPS only (enforce SSL)
¶ Best Practices
¶ Use Separate API Keys
Create different API keys for different purposes:
Production API Key:
- IP:
203.0.113.42(your production server) - Endpoint:
/api/tickets.json - Permissions: Minimal (only create tickets)
Development API Key:
- IP:
0.0.0.0(wildcard) - Endpoint:
/api/wildcard/tickets.json - Permissions: Full (for testing)
¶ Development Workflow
Recommended workflow:
-
Local Development
API_KEY=wildcard-dev-key-12345 ENDPOINT=http://localhost/osTicket/api/wildcard/tickets.json -
Staging Environment
# Use wildcard if behind firewall # OR use specific IP if publicly accessible API_KEY=wildcard-staging-key-67890 ENDPOINT=https://staging.example.com/api/wildcard/tickets.json -
Production Environment
# ALWAYS use specific IP for production API_KEY=production-key-specific-ip ENDPOINT=https://tickets.example.com/api/tickets.json # Standard endpoint!
¶ Multiple Developers
Best practice for teams:
-
Each developer gets their own wildcard API key
- Easier to track activity
- Can revoke individual access
- Better audit trail
-
Name API keys descriptively
Dev-John-Wildcard-Key Dev-Jane-Wildcard-Key Dev-Bob-Wildcard-Key -
Rotate API Keys Regularly
# Every 30-90 days 1. Create new API key with 0.0.0.0 2. Update applications 3. Delete old API key
¶ Disable in Production
Before deploying to production:
# Disable wildcard plugin
Admin Panel → Manage → Plugins → API Key Wildcard → Disable
# Use standard API with specific IPs
Admin Panel → Manage → API Keys → Update IP to specific address
¶ FAQ
¶ General Questions
Q: Does this plugin modify osTicket core files?
A: No! The plugin creates a separate endpoint and does NOT modify any osTicket core files. Standard API remains unchanged and secure.
Q: Can I use both endpoints simultaneously?
A: Yes! Standard API for production integrations (strict IP), wildcard API for development (flexible IP).
Q: Does this work with osTicket 1.17 or older?
A: Not tested. The plugin is designed for osTicket 1.18.x. It may work with 1.17, but compatibility is not guaranteed.
¶ Compatibility
Q: Is it compatible with PHP 8.x?
A: Yes! The plugin is tested with PHP 7.4, 8.0, 8.1, 8.2, and 8.3.
Q: Does this work with NGINX?
A: Yes, but requires manual configuration (see installation section). Apache setup is automatic.
Q: Can I use this with the API Endpoints Plugin?
A: Yes! All extended API endpoints work through the wildcard endpoint too.
¶ Security
Q: Is this safe for production?
A: NO! Only use wildcard API keys (0.0.0.0) in development/testing environments. Production should always use specific IP addresses.
Q: What happens if my wildcard API key leaks?
A: Anyone with the key can create tickets from anywhere. Immediately:
- Disable the API key in Admin Panel
- Create a new API key
- Update your applications
- Check logs for suspicious activity
Q: Can I restrict wildcard keys to specific IP ranges?
A: Not currently. The plugin only supports 0.0.0.0 (all IPs). For IP ranges, use the standard API endpoint.
¶ 📄 License
This Plugin is released under the GNU General Public License v2, compatible with osTicket core.
See LICENSE for details.
¶ 💬 Support
For questions or issues, please create an issue on GitHub:
Issue Tracker: https://github.com/markus-michalski/osticket-api-key-wildcard/issues
When reporting issues, please include:
- osTicket version (Admin Panel → Settings → About)
- PHP version (
php -v) - Web server (Apache/NGINX)
- Error messages from logs
- Steps to reproduce
¶ 🤝 Contributing
Developed by Markus Michalski
Contributions welcome!
- Fork the repository
- Create a feature branch
- Submit a pull request
Ideas for contributions:
- Support for IP ranges (e.g.,
192.168.1.0/24) - Configuration UI for enabling/disabling wildcard per key
- API usage statistics/monitoring
- Rate limiting for wildcard keys
¶ Changelog
See CHANGELOG.md for version history.