API Threat Protection

API threat protection

New in 5.1.0 · #287 · System → API → Threat protection, and each key's Edit window · Developers: API threat protection — Developer Guide

An API key is a password that never gets tired. If one leaks - left in a script on a shared drive, pasted into a ticket, committed to a repository - whoever finds it can do everything the key can, as fast as they like, at three in the morning. Threat protection makes that hard, noisy and short-lived.

The first line of defence: a key is one person

Every API key acts as one analyst and can never see more than that person: their companies, their modules, the projects they may see (members-only included), and a document only when they can see at least one record it is attached to. A key made for someone in Facilities cannot reach HR's documents.

🔑 Make integration keys for a dedicated, limited analyst - never an administrator. An administrator's key sees everything an administrator sees.

Each key: where and when

In a key's Edit window, the Where and when box (all optional - blank means any address, any time):

Setting	What it does
Allowed addresses	One address or range per line - 203.0.113.7, 10.20.0.0/16, IPv6 too. Requests from anywhere else are refused. The best protection there is against a stolen key: whoever took it is not on your network.
Allowed hours	Days and a time window, in the server's time zone - Mon-Fri, 07:00-19:00. Outside it: Refuse the request, or Allow it, but alert administrators. A window that ends before it starts (22:00-06:00) runs past midnight.
Download limits for this key	Its own alert and stop levels for document downloads. Blank uses the Threat protection tab.

⚠️ Behind a reverse proxy (some Docker set-ups), every request arrives from the proxy, so an allowed-address list must name the proxy. FreeITSM uses the address the connection really came from, never a header the caller writes.

The key list marks a key with restrictions as Restricted, shows its downloads in the last hour, and - if threat protection switched it off - why.

Threat protection

System → API → Threat protection (administrators). Every alert goes to administrators by bell and email (from the first mailbox that can send), at most once an hour for the same key and reason.

Watching for	What happens	Default
Document downloads - many files or a lot of data in an hour	Past the alert level, administrators are told. At the limit, further downloads are refused until the hour has passed - or, if you choose, the key is switched off.	Alert at 50 files or 500 MB an hour; stop at 200 files or 2 GB
Probing - a key refused again and again (403 or 404)	Alert, then switch the key off.	Alert at 20, off at 100, in 10 minutes
Key guessing - an address sending missing or wrong keys	That address is blocked from the API for a while, and administrators are told.	50 bad keys in 15 minutes blocks it for 15 minutes
A new address - a key used from somewhere it has not been used in 30 days	Alert only - never a block. Choose bell and email, bell only, or nobody.	Bell and email
Outside a key's address list or hours	Refused (or, for hours, allowed with an alert), and logged.	Set per key
A key that acts as an administrator	Allowed (with a warning), allowed only with allowed addresses, or not allowed. Checked on every request, so an analyst made an administrator after their key was created is caught too.	Allowed (with a warning)

💡 Why probing and "working through ids" are one rule. FreeITSM answers "not yours" and "does not exist" exactly the same way, on purpose - so nobody can find out what exists by asking. That means someone trying ids they should not have and someone stepping through numbers look the same: a key refused again and again.

0 switches the probing and key-guessing watchers off.

Keys that act as an administrator

An administrator's key sees everything. Two things need one - analyst provisioning (/analysts) and, unless the analyst reaches every company, job health (/jobs/health) - which is why there is no hard ban. The key list marks such keys Administrator, and the key window warns when you choose one. Allowed only with allowed addresses is the setting to choose if you use provisioning: it keeps working, and a stolen administrator key is useless off your network.

The log

Below the settings, Log lists every alert and refusal, newest first - when, which key, what, from which address, and the detail - filtered by key or by kind. It is the first place to look when a key is switched off.

A key switched off

The key list says it was switched off and why ("more than 200 files in an hour", "100 refused requests in 10 minutes"). An integration using it gets 403 key_disabled with the same reason. Read the log, decide whether it was a real problem, then switch it back on - or delete it and issue a new key.

The activity log

System → API → Activity - one row per API and MCP call: when, which key (or no valid key), the method and path, the status and error code, how long it took, the size and the address. Never what was sent or returned. Filter by key, failures only or part of the path; each key on the Keys tab shows its calls and failures today. Reporting → Logs links here.

Setting	Default
Record successful calls	Yes (failures are always recorded)
Keep for (days)	30
Older rows	Delete them - or archive them to a zip, then delete
One zip per (archive only)	Month - or day, or week

The tidy-up is the background job API activity log tidy-up, once a day, on Reporting → System logs → Background jobs with every other job - so the log keeps exactly the days you set, and a failed tidy-up shows there. Archived days go into their period's zip, a CSV per day inside, named by the first and last record: api-log-20261001-20261031.zip (renamed as later days join it). A day is deleted only once its zip is written and checked. Archives, on the same tab, downloads or deletes them; the folder (uploads/api-log-archive/) is never served directly.

Downloading documents needs its own permission

Document contents: download is a separate permission. It is never ticked by Select all, no existing key has it, and the key form shows it highlighted. A key that files paperwork onto projects needs only Projects: update - give download only to a key that genuinely has to take files away. Every download through the API is logged with the key, the address and the size.

What FreeITSM deliberately does not do

• No bulk download - one document per request, only through its record. No zip, no "everything" route.
• No public or pre-signed links - every byte goes through FreeITSM's checks.
• No geo-location ("access from an unexpected country") - it needs a licensed database that goes stale on offline installs, and VPNs and cloud hosts defeat it. Allowed addresses and the new-address alert do the job better.

Related

• REST API: Projects → Documents
• Project documents in the API - design
• Security