API Key Wildcard: Troubleshooting

Troubleshooting API Key Wildcard: 404 on the endpoint, the four 401 messages, missing log entry, updates not applied, wrong folder name and frequently asked questions.

Deutsche Version

Back to overview

API Key Wildcard: Troubleshooting

Problem: 404 on the wildcard endpoint

Symptoms:

/api/wildcard/tickets.json returns 404.
The plugin is enabled, but the file is missing or the rule is not in api/.htaccess.

Check:

Does api/wildcard.php exist?
Is the rule RewriteRule ^wildcard/(.*)$ wildcard.php/$1 [L] in api/.htaccess?
Is Options -MultiViews in api/.htaccess?
Is mod_rewrite active and does your web server evaluate .htaccess?
Does the web server user have write access to the api/ directory and to api/.htaccess?

Solution: Deactivate the plugin and activate it again, enable() copies the file again and extends the .htaccess. The errors reported during that (for example Could not find osTicket API rewrite pattern) name the cause. Alternatively install manually (see Installation).

Problem: 401 from the wildcard endpoint

The endpoint knows four messages. They appear in the language of the osTicket interface, in the English default as shown here.

Message	Cause	Solution
`Valid API key required`	The request contains no key.	Send the `X-API-Key` header.
`API key not found or IP not authorized`	The key does not exist, or its IP is neither `0.0.0.0` nor the caller's IP.	Check the key and set its IP to `0.0.0.0`.
`API key not active`	The key is deactivated.	Activate the key in the Admin Panel.
`Source IP not authorized`	The key's IP differs from both `0.0.0.0` and the caller's IP.	Check the key's IP.

Also make sure you call /api/wildcard/tickets.json with the POST method and that the key has the Can Create Tickets permission.

Problem: The key does not work on another plugin's endpoint

Routes of other plugins that register on the wildcard dispatcher via the api signal check the key themselves. The wildcard rule does not apply there. See Usage.

Problem: Fatal error or 500 on the endpoint

Cause: The plugin folder is not named api-key-wildcard. wildcard.php loads include/plugins/api-key-wildcard/api.wildcard.inc.php through this fixed path.

Solution: Rename the folder to api-key-wildcard and activate the plugin again.

Problem: No log entry for wildcard access

The Log Wildcard API Access option must be enabled.
Only requests made with a key whose IP is 0.0.0.0 create an entry, keys with a fixed IP do not.
The entry is a debug entry and appears only if osTicket's log level allows debug messages.

Problem: Plugin update is not applied

The update of the endpoint file only runs when installed_version is empty or lower than the version in plugin.php. If files were replaced without a version change, the old api/wildcard.php stays in place.

Solution: Deactivate and activate the plugin, enable() always copies the file again. If needed, clear the PHP OPcache so changed plugin files are loaded.

Frequently asked questions

Does the plugin change osTicket files?

It changes no PHP files of osTicket. It copies wildcard.php to api/ and extends api/.htaccess.

Can I use both endpoints at the same time?

Yes. The standard endpoint stays unchanged, the wildcard endpoint is added next to it.

What happens on deactivation?

api/wildcard.php is deleted and the wildcard rule and Options -MultiViews are removed from api/.htaccess.

Which PHP versions are tested?

The CI checks the syntax with PHP 7.4, 8.0, 8.1, 8.2 and 8.3.

Are there tests for the plugin?

The repository contains no test suite. The CI checks the syntax of all PHP files, the presence of the required files, the plugin metadata (name and version in plugin.php), searches the PHP files for eval( and base64_decode (a match fails the CI), checks that README.md exists, and checks that CHANGELOG.md has an [Unreleased] section.