Deutsche Version

Back to overview

API Endpoints: Installation

This documentation always describes the latest published version.

Requirements

The plugin has no runtime dependencies, Composer is not needed on the server.

Step 1: Install Plugin Files

ZIP Download

1. Download the latest release from Releases
2. Extract the ZIP file
3. Upload the api-endpoints folder to /include/plugins/ on your osTicket server

Git Clone

cd /path/to/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-api-endpoints.git api-endpoints

The folder must be named api-endpoints, so the final path is /path/to/osticket/include/plugins/api-endpoints/. The deployed endpoint files load the plugin from exactly this path. Under a different folder name they fail with 500 (API Endpoints Plugin not properly installed).

Step 2: Enable the Plugin

1. Log in to the osTicket Admin Panel
2. Open Manage → Plugins
3. Install API Endpoints if it is not installed yet, then enable it

On enabling, the plugin does the following:

• creates its single plugin instance
• removes tickets-*.php files and its rewrite block left over from an earlier installation
• adds the permission columns can_update_tickets, can_read_tickets, can_search_tickets, can_delete_tickets, can_read_stats and can_manage_subtickets to the API key table, all disabled by default
• copies the files from the plugin's api/ folder into the /api/ folder of your osTicket installation
• inserts its rewrite rules into /api/.htaccess
• stores the installed version

When the plugin version changes after an update, the columns, files and rules are redeployed automatically on the next request.

The plugin does not patch any osTicket core file. It does add files to /api/, rules to /api/.htaccess and columns to the API key table.

Step 3: Web Server

Apache (automatic)

osTicket ships /api/.htaccess. The plugin inserts the rules of its htaccess.template there, after the wildcard rule of the API Key Wildcard plugin if present, otherwise before the default API rule. Each rule lets one endpoint file through directly, for example:

RewriteRule ^tickets-get\.php/ - [L]
RewriteRule ^tickets-update\.php/ - [L]
RewriteRule ^tickets-search\.php.*$ - [L]

If /api/.htaccess does not exist or no insertion point is found, the plugin's enable() returns a warning message and you have to add the rules from htaccess.template yourself. The directory must allow .htaccess overrides (AllowOverride).

NGINX (manual)

The plugin does not touch the NGINX configuration. Eight endpoint files take their parameter as PATH_INFO: get, update, delete, attachment-download and all four subticket endpoints. Add this to your server block and adjust the PHP-FPM socket:

# Endpoints with PATH_INFO, for example /api/tickets-get.php/123456.json
location ~ ^/api/tickets-(?:get|update|delete|attachment-download|subtickets-(?:parent|list|create|unlink))\.php/ {
    fastcgi_split_path_info ^(/api/tickets-[a-z-]+\.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;
}

# Endpoints without PATH_INFO, for example /api/tickets-search.php?query=test
location ~ ^/api/tickets-(?:search|stats|statuses)\.php$ {
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
    fastcgi_pass unix:/var/run/php/php-fpm.sock;
}

sudo nginx -t
sudo systemctl reload nginx

Step 4: Verify

An API key with the permission can_read_stats or can_read_tickets must get the status list:

curl "https://your-domain.com/api/tickets-statuses.php" \
  -H "X-API-Key: YOUR_API_KEY"

404 means the web server does not pass the file through, see Troubleshooting. 401 means the key lacks the permission, see Configuration.

Update

Replace the contents of the api-endpoints folder with the new version. With the next request after the version change the plugin updates the columns, copies the endpoint files again and replaces its block in /api/.htaccess.

Disabling and Removal

Disabling the plugin in the Admin Panel changes nothing in /api/. The deployed endpoint files stay reachable and are still protected by the API key permissions. Only the two routes POST /api/tickets.json and PATCH /api/tickets/{number}.json are no longer extended.

To remove the plugin completely:

1. Disable the plugin and remove the plugin from the list in Manage → Plugins
2. Delete the plugin folder /include/plugins/api-endpoints/
3. Delete the files tickets-*.php from /api/
4. Remove the block that starts with API Endpoints Plugin - Apache Rewrite Rules from /api/.htaccess, but keep the rest of the file
5. Optional: drop the six permission columns from the API key table

Do not delete /api/.htaccess itself, osTicket needs it. Tickets and attachments are not affected by removing the plugin.