Install

Requirements

• HESK 3.7.x (developed against 3.7.11)
• PHP 8.1+ with pdo_mysql, json, mbstring, openssl
• PHP-FPM + nginx (Apache with FallbackResource also works)
• The HESK MySQL database (the installer adds two *_api_* tables)
• A hostname and TLS certificate for the API (a separate vhost is the usual layout)

1. Unpack

unzip hesk-api-1.4.0.zip
sudo mkdir -p /var/www/hesk-api
sudo rsync -a hesk-api-1.4.0/ /var/www/hesk-api/
sudo chown -R www-data:www-data /var/www/hesk-api/storage
sudo chmod -R ug+rwX /var/www/hesk-api/storage

Adjust the web user (www-data, nginx, apache) to match the host.

2. Point the installer at HESK

cd /var/www/hesk-api
sudo -u www-data php bin/install.php \
  --hesk-path=/var/www/hesk \
  --api-url=https://api.help.example.com \
  --create-token --user=admin --name=Bootstrap

Flag	Meaning
--hesk-path	Directory that contains hesk_settings.inc.php
--api-url	Public URL of this API (no trailing slash)
--hesk-url	Public HESK URL (defaults to HESK’s own hesk_url)
--api-prefix	REST prefix, default /v1
--utf8mb4	Optional: convert ticket/reply text columns to utf8mb4 (emoji)
--create-token	Mint a staff token after schema install
--force	Overwrite config/config.local.php

The installer writes config/config.local.php and adds {prefix}api_tokens and {prefix}api_audit_log. {prefix} is whatever HESK already uses (hesk_ by default). Save the bootstrap token when it is printed — it cannot be retrieved later.

3. Web server

Copy deploy/nginx-hesk-api.conf.example, set server_name and root to …/hesk-api/public, enable the site, reload nginx, then issue TLS. The document root must be public/. Do not expose config/, src/, or storage/.

curl -sS https://api.help.example.com/health

You should see "status":"ok" and a version field. Then open /docs (Swagger UI) and /login (staff token portal).

4. Create tokens

Staff sign in at /login with their HESK staff username and password. Each token inherits that user’s categories, privileges, and admin flag.

php bin/create-token.php --user=admin --name="CI"

Authorization: Bearer hsk_…

X-API-Key: hsk_… is also accepted.

Customization

Shipped defaults live in config/config.php. Host overrides go in config/config.local.php (the installer writes this file). Environment variables HESK_PATH, HESK_URL, and HESK_API_URL also override the matching keys.

Paths and URLs

'hesk_path' => '/var/www/hesk',
'hesk_url'  => 'https://help.example.com',
'api_url'   => 'https://api.help.example.com',
'api_prefix'=> '/v1',

api_url is rewritten into the live /openapi.json servers list so Swagger “Try it out” hits this install.

Branding

'branding' => [
    'product_name' => 'HESK API',
    'vendor'       => 'Your Company',
    'vendor_url'   => 'https://example.com',
],

Tokens

'token' => [
    'prefix'           => 'hsk_',
    'secret_bytes'     => 32,
    'default_ttl_days' => null,     // null = never expires
    'max_per_user'     => 20,
],

Rate limits

'rate_limit' => [
    'enabled'        => true,
    'requests'       => 120,
    'window_seconds' => 60,
],

Limits are per token (or per IP before a token is presented).

CORS

'cors' => [
    'allowed_origins' => ['https://app.example.com'],  // or ['*']
    'allowed_methods' => 'GET, POST, PUT, PATCH, DELETE, OPTIONS',
    'allowed_headers' => 'Authorization, Content-Type, X-Requested-With, X-API-Key',
],

Logging, pagination, debug

'log' => [
    'enabled'  => true,
    'path'     => __DIR__ . '/../storage/logs/api.log',
    'log_body' => false,
],
'pagination' => [
    'default_limit' => 25,
    'max_limit'     => 100,
],
'debug' => false,
'timezone' => 'UTC',

Leave debug off in production. Never log Authorization or raw bodies.

Table prefix

Taken from HESK (db_pfix). You do not set it in the API config.

PHP-FPM / nginx

The sample vhost uses unix:/run/php/php8.3-fpm.sock. Change the socket (or use 127.0.0.1:9000) to match the host. Raise fastcgi_read_timeout if you upload large attachments.

Attachments

Size, count, and allowed extensions come from HESK attachment settings. Confirm with GET /v1/attachments/limits. PHP upload_max_filesize and post_max_size also apply.

Unicode / emoji

HESK 3.7 ships some text columns as utf8mb3. If ticket create fails on 4-byte UTF-8:

php bin/install.php --hesk-path=… --api-url=… --force --utf8mb4

or apply sql/utf8mb4-message-columns.sql (prefix-aware via the installer).

Apache

Document root = public/. Enable mod_rewrite and:

FallbackResource /index.php

or an equivalent rewrite of all non-files to index.php.

Upgrading

1. Unpack the new zip next to the old tree.
2. Copy config/config.local.php (and anything you added under storage/) into the new tree.
3. Run php bin/install-schema.php — it is safe to re-run (CREATE TABLE IF NOT EXISTS).
4. Reload PHP-FPM if opcache is on.

Do not overwrite config.local.php with the example file.

Uninstall

Remove the vhost and the API directory. Drop {prefix}api_tokens and {prefix}api_audit_log if you want the database clean. HESK itself is unchanged.