Demo
Demo

Knowledge base

PMTA knowledge base›Block Global›Directive§ 3.3.1.58.5

http-api-key

Globalcriticalrestart requiredset by the Hub

Keys that grant full access to all of the node's HTTP interfaces
in the configuration this is a linehttp-api-keyinside the block Global
One key — full access to the node

The line declares a key that the client passes in the X-API-Key header. Length from 32 to 128 characters, letters, digits and underscore, case-sensitive. The line is repeatable — there can be several keys, for example one per application.

The key opens not just the monitor but four things at once: the web monitor itself with administrator rights; the configuration files API (§ 8.2) — reading, writing and listing the node’s configuration files; the configuration API (§ 8.3) — editing address lists and sending addresses; the command API (§ 8.4) — almost all console commands over HTTP.

The key is stronger than the address restriction. The manual says this twice and word for word: a valid key overrides everything set in http-access, and requests are accepted from any address. This is not a second factor but a bypass of the first.

So the key equals access to the node — and to its configuration. Whoever has it can rewrite the configuration file through the API and reload the engine.

The main trap is treating the key like a panel password rather than like root access. It sits in the configuration file in plain text; the file gets read, copied, put into version control systems and sent to support — together with the key. The permissions on the file are worth exactly as much here as the key itself.
What the Hub does. It writes it — one key per node, in the telemetry block. The key is stored encrypted in node_engines.api_key_encrypted and is not shown in the interface. There are never two valid keys at once: the configuration is rewritten as a whole, and the old line disappears.

🔴 But the key goes over the wire in plain text. Polling runs over plain http:// — NodePoller, PmtaMonitor and PmtaCommander put it into the header unencrypted, and our base configuration has http-redirect-to-https set to false. A key that can rewrite the node’s configuration and run any command crosses the network in the clear on every poll. Storage is encrypted, transmission is not.

Recommended values

The key is long and random, otherwise it is not a key:

What How
length from 32 to 128 characters
character set Latin letters, digits, underscore
case matters
how many as many as needed; the line is repeatable

Different applications get different keys. Then revoking one does not break the others: one line is removed.

The length, the character set and repeatability come from the manual (§ 3.3.1.58.5, § 8.1.3). That the key overrides the address restriction and opens three APIs comes from there too (§ 8.2, § 8.3, § 8.4). The analysis of our storage and transmission scheme is based on the Hub’s code.
Example configuration
# different applications get different keys: revoking one does not break the others
http-api-key abcd_0123_abcd_0123_abcd_0123_ab   # Hub telemetryhttp-api-key 5f6e7e426949e3a5e4ec38e747e71963   # report export
An example from the manual with our comments. A comment next to a key is the only way to understand later whose it is and what will break when it is revoked.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends3 mistakes▶

Treating the key as a second factor on top of the address list

§ 8.2

What it costsThe key does not supplement the list, it overrides it. A monitor closed by address and equipped with a key is open to the whole world for anyone who has the key.
How to spot itThe access list has a narrow range, yet the log shows successful requests from outside.
How to do it rightTreat the key as equal to root access to the node: store, transmit and revoke it accordingly.

Transmitting the key over an unencrypted connection

our experience

What it costsThe header is visible to anyone along the way. Whoever intercepts it gets the right to rewrite the node’s configuration and run any command.
How to spot itThe configuration has http-redirect-to-https set to false, and the client goes over http://.
How to do it rightEnable the redirect to https and teach the client to trust the monitor’s certificate — it is self-signed and stored as the file /var/lib/pmta/webmon.pem.

One key for all applications

our experience

What it costsRevoking the key breaks all of them at once, so it is never revoked — even when it should be.
How to spot itThe file has one key line, but the key has several users.
How to do it rightOne key per application, with a comment next to each.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Reference data
Syntax
http-api-key STRING
Values
a string of 32 to 128 characters made of Latin letters, digits and underscores
Applying
a service restart is required
Queue
will not touch what is already queued
Where to write it
Global
How many times
may be repeated
Everything here comes from the manual, with the section.
Inheritance
There is no inheritance: the lines are written at the root of the file, in the Global section, and apply to the whole node. Keys are not split by interface: any declared key opens all four — the monitor, both configuration APIs and the command API. A separate key for HTTP submission is a different line, api-key in <transmissions-api>.
⇄

Related directives

4 relations

Does not work without

Lock down permissions on configuration filesThe key sits in the file in plain text, so the permissions on the file are worth as much as the key itself. § 1.6.3

Can be replaced by

http-accessGlobalTwo ways to let someone in, and this one is stronger: a valid key overrides the address restriction. § 3.3.1.58.5

Applies to

http-mgmt-portGlobalAll three HTTP interfaces that the key opens listen on this port. § 8.4

Often used with

Change a signing key without interrupting sendingChanging the key works the same way as changing a signing key: the new one is written, and the old one stops working on apply. inference

Referenced from

http-csrf-protectionGlobalA request with a valid key does not pass the protection but bypasses it: the key takes the place of the session token. § 3.3.1.58.4http-enable-api-configGlobalReading may pass by access level, but editing always requires a key. § 8.3api-key<transmissions-api>The key for a different entry point — the web monitor and the management HTTP API; the names are similar, the rights are different. § 3.3.20.1How the node decides whether to let an HTTP request inThe key is the second way to identify yourself, and it is stronger than the first. § 8.2

How to check on the node
We check the key the same way it is used — from an address that is not allowed access:
curl -s -H 'X-API-Key: KEY' -o /dev/null -w '%{http_code}\n' http://NODE:1000/status
200 from a disallowed address means the key works and the address restriction does not apply to it — that is, everything is as the vendor intended. The same key also checks the command API: curl -H ‘X-API-Key: KEY’ http://NODE:1000/command -F command=’show version’ -F format=json.
◇

What else to read

3 articles

◇The vendor's analytics — and what leaves the node for itA paid service that receives the node’s accounting data and returns analytics, a health score and a spam trap report; it is enabled by scope and stays off until its block exists.◇Exposing metrics over SNMPThe node can expose its metrics over SNMP — a second way of monitoring besides the web monitor.◇What the node tells about itself and through which channelsSeven observation surfaces: the web monitor, the console in four formats, the log, accounting, accounting search, metrics and export to external analytics.

In the Hub
Managed at
Infrastructure → Node parameters
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
reversible: harms only while it is set
Scenarios
Node security · Collect telemetry
Priority
critical
Neighboring settings of the block Global:http-accessrun-as-roothttp-csrf-protectionhttp-redirect-to-httpslog-file-world-readableAll 108 directives of the block →