¶ API Key Wildcard Plugin v2.0
¶ Table of Contents
- Overview
- Key Features
- Use Cases
- Requirements
- Installation
- Configuration
- Usage
- Signal Hooks
- Troubleshooting
- Technical Details
- 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.
Without this plugin: osTicket's native API requires a fixed IP address per API key. With dynamic IPs (home office, CI/CD, changing locations), the key must be manually updated constantly.
With this plugin: A separate wildcard endpoint allows API keys with IP
0.0.0.0to accept requests from any IP address. The standard endpoint remains unchanged and secure.
Wildcard API keys (
0.0.0.0) are intended for development environments only! In production environments, API keys should always be bound to specific IP addresses.
¶ 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 needed
- ✅ Automatic Updates - Version detection and auto-update on plugin file changes
- ✅ Modular Architecture (v2.0) - Single Responsibility Principle, 4 specialized classes
- ✅ Configurable Logging - Optionally log wildcard access to debug log
- ✅ XSS Protection - Remote IPs are sanitized before logging
- ✅ Apache & NGINX Support - Works with both web servers
- ✅ Clean Uninstall - Disabling removes all files and .htaccess changes
¶ 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, on the go)
¶ 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 |
No external dependencies. No Composer required.
¶ Installation
- Download latest release from GitHub 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/
cd /path/to/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-api-key-wildcard.git api-key-wildcard
¶ 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:
wildcard.phpis copied to the/api/directory (chmod 0755)/api/.htaccessreceivesOptions -MultiViewsand wildcard rewrite rule- Installation details are written to the error log
- Installed version is saved in plugin configuration
¶ 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
The API key MUST have IP
0.0.0.0to work with the wildcard endpoint!
¶ Manual Installation (Fallback)
If 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]
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;
}
sudo nginx -t
sudo systemctl reload nginx
¶ Configuration
The plugin offers two settings in the Admin Panel (Plugins → API Key Wildcard → Configuration):
| Setting | Description | Default | When to use |
|---|---|---|---|
| Installed Version | Shows the currently installed plugin version (readonly) | Automatic | To verify auto-update worked correctly |
| Log Wildcard Access | Logs each wildcard API access to the debug log | Enabled | Disable with high API volume to avoid log spam |
When "Log Wildcard Access" is enabled, each successful wildcard access creates a debug entry with the remote IP in osTicket's system log. The IP is XSS-protected using
Format::htmlchars(Format::sanitize()).
¶ 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 IP = 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 via Wildcard",
"message": "This is a test message via the wildcard endpoint"
}' \
http://localhost/osTicket/api/wildcard/tickets.json
Use
/api/wildcard/tickets.json(NOT/api/tickets.json). The standard endpoint continues to work normally with IP-bound keys.
¶ Supported Formats
| Standard Endpoint | Wildcard Endpoint |
|---|---|
/api/tickets.json |
/api/wildcard/tickets.json |
/api/tickets.xml |
/api/wildcard/tickets.xml |
/api/tickets.email |
/api/wildcard/tickets.email |
Also works with extended API endpoints from other plugins (e.g., API Endpoints Plugin)!
¶ Signal Hooks
The plugin does not use osTicket's signal system directly but overrides API controller logic:
| Mechanism | Class | Purpose |
|---|---|---|
enable() Hook |
ApiKeyWildcardPlugin |
Installs endpoint file and .htaccess rules |
disable() Hook |
ApiKeyWildcardPlugin |
Removes endpoint file and .htaccess changes |
bootstrap() Hook |
ApiKeyWildcardPlugin |
Checks for version mismatch and triggers auto-update |
requireApiKey() Override |
WildcardApiController |
Modified API key validation with 0.0.0.0 support |
¶ Troubleshooting
¶ Problem: Automatic Installation Failed
Symptoms:
- Plugin enabled but
/api/wildcard/tickets.jsonreturns 404 - No
wildcard.phpin/api/directory
Check:
- File exists?
ls /path/to/osticket/api/wildcard.php - Check error log:
tail -f /var/log/apache2/error.log - File permissions: Web server must have write access to
/api/
Solution: Use manual installation (see installation section above)
¶ Problem: 401 Unauthorized Error
Symptoms:
- Request to wildcard endpoint returns 401
- Error message: "Valid API key required"
Check:
- API key IP address: Admin Panel → API Keys → IP must be
0.0.0.0 - Correct endpoint:
/api/wildcard/tickets.json(not/api/tickets.json) - API key active? Check Admin Panel → API Keys
- Header present?
X-API-Key: YOUR_KEYmust be in request
Solution:
# Correct request:
curl -X POST \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Test","email":"test@test.com","subject":"Test","message":"Test"}' \
http://localhost/osTicket/api/wildcard/tickets.json
¶ Problem: 404 Not Found Error
Symptoms:
/api/wildcard/tickets.jsonreturns 404- No rewrite rule in
.htaccess
Check:
- Endpoint file present?
ls -la /path/to/osticket/api/wildcard.php - .htaccess rule present?
grep wildcard /path/to/osticket/api/.htaccess - mod_rewrite enabled?
apache2ctl -M | grep rewrite - MultiViews disabled?
grep MultiViews /path/to/osticket/api/.htaccess
Solution: Disable/enable plugin to retrigger installation, or install manually.
¶ Problem: Plugin Updates Not Applied
Symptoms:
- Plugin files updated but
wildcard.phpin/api/is still old version - Installed version in plugin configuration doesn't match plugin.php
Solution:
- Clear PHP OpCode cache:
sudo systemctl reload php8.1-fpm # PHP-FPM sudo systemctl reload apache2 # Apache mod_php - Disable and re-enable plugin (retriggers
enable()) - Check version in plugin configuration
Since v2.0, the plugin automatically detects version mismatches during bootstrap and performs auto-updates.
¶ Technical Details
¶ Architecture (v2.0 - Modular Classes)
¶ Class Overview
¶ File Structure
api-key-wildcard/
├── plugin.php # Plugin registration (ID, version, author)
├── class.ApiKeyWildcard.php # Main plugin class + config
├── class.PluginConstants.php # All magic strings centralized
├── class.PluginInstaller.php # File operations (install/uninstall)
├── class.HtaccessManager.php # .htaccess manipulation
├── api.wildcard.inc.php # WildcardApiController (core logic)
├── wildcard.php # API endpoint (copied to /api/)
├── .htaccess # Reference htaccess with wildcard rules
├── CHANGELOG.md # Version history
├── LICENSE # GPL v2
└── README.md # Documentation
¶ Security Mechanism
Standard API (/api/tickets.json):
// Checks IP address against API key configuration
WHERE apikey = ? AND ipaddr = ? -- Client IP must match exactly
Wildcard API (/api/wildcard/tickets.json):
// Extended check: IP match OR wildcard IP
WHERE apikey = ? AND (ipaddr = ? OR ipaddr = '0.0.0.0')
The remote IP is protected against XSS attacks in the access log using
Format::htmlchars(Format::sanitize())- even with manipulated X-Forwarded-For headers.
¶ Auto-Update Mechanism
Since v2.0, the plugin tracks its installed version via plugin configuration (no longer via .htaccess comments):
- On each
bootstrap(): Read installed version from config - Compare with current
plugin.phpversion - On mismatch: Call
performUpdate() - Update reinstalls endpoint file and .htaccess rules
- Save new version in config + log entry
¶ Security Considerations
¶ When NOT to Use Wildcard Keys
- Public-facing production servers
- Servers handling sensitive data
- Compliance-regulated environments (PCI-DSS, HIPAA, etc.)
- Shared hosting environments
¶ Safe Usage Scenarios
- Development environments (localhost)
- Internal networks behind firewalls
- Testing/staging environments (non-public)
- Personal projects with low security requirements
¶ Best Practices
Use separate API keys:
| Environment | IP | Endpoint | Notes |
|---|---|---|---|
| Production | 203.0.113.42 |
/api/tickets.json |
Specific IP, standard endpoint |
| Staging | 0.0.0.0 |
/api/wildcard/tickets.json |
Only behind firewall |
| Development | 0.0.0.0 |
/api/wildcard/tickets.json |
Separate key per developer |
Before deploying to production: Disable plugin (Admin Panel → Plugins → API Key Wildcard → Disable). All wildcard files and .htaccess changes are automatically removed.
¶ FAQ
¶ General
Q: Does this plugin modify osTicket core files?
A: No. The plugin creates a separate endpoint and does not modify any core files. Standard API remains unchanged.
Q: Can I use both endpoints simultaneously?
A: Yes. Standard API for production integrations (strict IP), wildcard API for development (flexible IP).
Q: What happens when disabling?
A: The plugin cleanly removes all installed files (/api/wildcard.php) and all .htaccess changes. No manual cleanup needed.
¶ Compatibility
Q: Which PHP versions are supported?
A: PHP 7.4, 8.0, 8.1, 8.2, and 8.3 (tested in CI).
Q: Does this work with NGINX?
A: Yes, but requires manual configuration (see installation section). Apache setup is automatic.
Q: Compatible 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.
Q: What happens if my wildcard API key leaks?
A: Anyone with the key can create tickets from anywhere. Immediately: Disable API key in Admin Panel, create new key, check logs for suspicious activity.
¶ License
GNU General Public License v2, compatible with osTicket core.
See LICENSE.
¶ Support
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
- Installed plugin version (plugin configuration)
¶ Changelog
See CHANGELOG.md for full version history.